This webtrees module hosts Lineage, a node-link diagram that visualizes genealogical relationships. Lineage was originally developed by Ben Garvey, I came across it at the time in an adapted version on Jens-Peter Stern's homepage.
- Copyright (C) 2022/2025 huhwt - EW.H
The version presented here combines the concepts of the originals with elements from TAM and own extensions (TAM: Topographic Attribute Maps).
This is a webtrees 2.2 module - It cannot be used with webtrees 2.1.
For webtrees 2.1 use the latest release of the huhwt-wtlin Branch 2.1.
This readme contains the following main sections
Lineage or LIN is a node-link diagram based on a D3.js force simulation. The nodes represent people, while the links show relationships (parent-child(ren)/partnership).
After data transfer, the display runs exclusively locally in the user's browser. With this technical platform, the display is highly dynamic and can respond immediately to a wide variety of settings.
(There is a downside: with large numbers of nodes—in the order of several thousand people—it will take some time (also depending on the performance of the local computer) for the display to build up and even longer for it to reach relative stability. One consolation: in tests, node numbers of 10,000+ with more than 30,000 links were handled stably over the long term.)
The data is extracted from Webtrees, with huhwt-cce serving as the interface. The data stored there in a session variable is rewritten to IndexedDB by the PHP part of this module. The actual LIN components access the information in IndexedDB and are therefore independent of the server side.
There is a fundamental content link to Webtrees in terms of the color scheme of the person nodes. In addition to the surname in plain text, Webtrees also offers implementation according to Soundex in both the standard and Daitch–Mokotoff variants (SoundDM). All three variants are adopted in LIN. The SoundDM variant serves as an index feature for the D3js color space interpolateSinebow. Family names that differ in upper and lower case or alternative umlaut spellings, for example, are displayed in the same color, unlike when the name is used in plain text.
-
The reference time is a central control variable and can be set and changed in various ways. Nodes outside the reference period are automatically hidden and, if the reference period is extended, they are displayed again. For details, see below - [Time control](#time control).
-
You can display a list of the persons shown in the view. For details, see below - Person list.
-
You also have the option of filtering the display by family name so that only nodes and connections of persons with selected names are displayed. The selection can be made using a fairly flexible list; the filter definitions are saved and can be activated as desired. For details, see below - Name control.
The primary display is the tree view with the links. Alternatively, persons can also be displayed in a timeline or a group view grouped by family name.
In the tree view, persons and relationships / nodes and their links / nodes and links are the central element, and the display focuses on the individual level. Unlike TAM, where families are a central element of the display, LIN displays the connection between parents and children individually and the relationship between the parents as a separate, visually distinct link.
The other two views focus on higher-level aspects.
In the group view, individuals are grouped according to their family names; relationships are not shown. The groups can be arranged in two different ways, and you can switch between Soundex variants for assigning individuals to groups.
In the timeline view, individuals are arranged on a timeline according to their date of birth; relationships are only displayed after an individual has been selected.
The complete Gedcom is imported from Webtrees, and all data contained therein is generally available. The relationships form the framework of the tree view, the date of birth is the reference for time control, and the name properties define the color scheme and are the reference for the group display.
However, the relevant information about a person is not only displayed graphically, but also textually in a tooltip when you hover over a person node with the mouse. If available, the assigned ‘shared notes’ are also displayed.
The display supports zoom and pan. By clicking on the display and then dragging, the entire display can be moved - PAN. The mouse wheel can be used to change the size of the view - ZOOM. ZOOM also takes the position of the mouse pointer into account; a ZOOM point outside the center of the display causes the entire image to shift. For easier orientation, a crosshair is superimposed on the entire display. Further options are described below.
This is an SVG construct, which means that the display can be enlarged or reduced as desired without any loss of sharpness or the need for complex conversions.
When the mouse pointer hovers over a node, the underlying information is displayed as a tooltip. Some of this information is included as accompanying text directly in the display, such as the name in the tree view or the classification criteria and numbers in the other views.
Clicking on a node doubles its size. If you drag it to another position in this state (DRAG-n-DROP), it will be fixed there, will no longer be subject to the iteration process, and will also stabilize the positions of the other nodes connected to it via links as a side effect. Clicking on the node again releases the fixation, the size is reset to its regular value, and the node follows the simulation effects again.
You can also fix a node by double-clicking it without dragging it to another position; it is highlighted as described and released again with a single click.
The display can be influenced and controlled in many areas. The instruments for this are divided into three areas:
- Left: Settings menu
- Top: Time control
- Right: General control surfaces
The rule of thumb for the various elements is: “If it turns green when you hover over it, click on it and something will happen.”
A comprehensive menu is displayed on the left side of the screen (click on the 'Menu' button to hide it). Here you can start read and write operations, switch between the views, activate/deactivate and change various options of the displays and set the reference time of the display.
he menu groups its options into different category boxes, some of which are always open, while others are opened by clicking on the box heading.
- Open/Store
- Nodal Views
- Individuals List
- Surname filter
- [Navigation] A time control element that offers jump marks at specific points in time — see there for more details.
- [Interaction] Controls aspects of TAM underlay—activation, underlay with contours, and additional display of year numbers.
- [Force.Layout] Controls aspects of the D3js force simulation. Changes here affect the density and agility of the graphical presentation. Details can be found in D3js itself – the rule is: ‘You can, but you shouldn't’ ...
- [Graph.Appearance] Controls aspects of the node connection display
- [Map.Appearance] Controls aspects of TAM processing
- [Language] Switches the label texts
The current tree view can be written to and read from an external file as well as from IndexedDB (IDB). When writing to an external file, the usual file dialog is opened; the file name is given by the record identifier, supplemented by the reference time, and can be customized as desired. When reading from an external file, the file name is used as the record identifier.
The dataset identifier is predefined by wtCCE during the download, it consists of the family tree abbreviation and the identifier of the last CCE action. In the screen view it can be overwritten as desired. The respective content is taken over by the write operations.
When reading, the respective file name(external) or the key expression (IDB) is taken over as data set identifier.
Writing to IDB is executed immediately, there is no explicit feedback. When reading IDB, an overview of the existing entries is shown, in this overview entries can also be removed to clean up the database.
When writing away, the respective state is documented completely and restored accordingly when reading. So you could prepare a view in the initial view by setting the reference time and dragging and fixing nodes to analyze and document a specific issue, and can then conserve this state by writing away for later resubmission, without having to meticulously repeat all the individual steps later ...
The ZOOM limits are set very wide so that you can control the display using this alone. In addition, however, the size of the viewbox (the technical screen element in which the display is anchored) can also be adjusted in several stages. In the default state, the viewbox size is set to 6x6 (6000x6000 pixels), which allows trees with up to 250 nodes to be displayed quite clearly. If the number of nodes is higher, it is likely that you will only get the full view by zooming in intensively. To make things easier, you can enlarge and reduce the viewbox in increments of 2 – if the viewbox is set to 9x9 or 12x12, the nodes are displayed smaller, but the overall view is possible without ZOOM. Alternatively, you can also set 4x4 and 2x2, in which case the nodes are significantly larger and the accompanying text in the display is also clearly visible.
It can be difficult to find specific persons in larger representations. This is due to the procedure: the positions result from the calculation of the attractive forces of the connections with mutual repulsion between the nodes, where a person is then positioned after the forces have been balanced, which is hardly predictable. It also has to do with the order in which the persons are arranged in the database. This is basically unordered; the sequence results from the sequence of collection actions, whereby the position of a person is determined by their first appearance in an action. The order of the persons during collection determines how they are entered into the process.
The overview of persons in the diagram is sorted by name (last name, first name). The sorting can be done in ascending or descending order.
There is a purely alphabetical view. In this view, subgroups can be selected according to the first letter of the last name (only if ‘A’-'Z'; undefined last names are ignored). Alternatively, the list of persons can also be displayed grouped by year, divided into decades (in this case, the additional selection by initial letter does not apply).
When hovering over the list entries, both these and the corresponding nodes in the diagram are briefly highlighted. Clicking on a list entry permanently marks both the list entry and the node.
Clicking on a marked entry again removes the highlighting of both the entry and the node. A button can also be used to remove all existing highlights at once.
Double-clicking on an entry forces a person to be placed in the center (internally, they are moved to the top of the order), and the display is rebuilt with this changed boundary condition. The person is highlighted as the “person in focus” both in the form header and in the list, and the node is displayed prominently in the diagram. The focus on the person is removed by double-clicking on the relevant entry again, by clicking a button next to the text field in the form header, or indirectly by focusing on another person.
Another addition to the Lineage Origin feature is the option to filter subsets of nodes by family name. You can call up a comprehensive list of family names, sorted either by frequency or alphabetically, and within the total set you can also filter by initial letter. Checkboxes can now be used to select names and save them as filter criteria. Multiple filter definitions can also be created and switched between as you proceed. As with the reference year, all nodes whose name criteria do not match the active filter are removed from the display. The relevant name criterion is determined according to the name scheme specification (see above). If, for example, SoundDM is set, all nodes corresponding to the SoundDM value of a name in the filter are displayed, even if their real names differ (if you select ‘Mayer’, you will also get ‘Meier’, ‘Meyer’, ‘Meir’, etc.).
By clicking on the “with partners” checkbox, the spouses assigned to each person selected via the active filter are also included in the display. The representative nodes are then displayed in reduced size.
The current reference time and the number of active and hidden nodes are displayed at the bottom of the screen. No further distinction is made with regard to the hidden nodes, i.e., no distinction is made as to whether the name or time period filter has been applied.
An important addition to the Lineage origin is the possibility to set the reference time of the display. The display period is preset to the time span from 1500 to the last relevant person date rounded up to smooth 10s of years. In the menu now appropriate jump marks are inserted in 50-year intervals, so that one can set the reference time on respective decade marks.
Remark: If a person date before 1500 should be needed, one can/must create hand. The preparation is controlled over 2 parameters - YEARshowMIN -> is converted as earliest permissible person date - YEARrangeMIN -> is converted as starting year of the representation. The values are defined as constants in the header of the JavaSript coding parms.js and would have to be adjusted once according to the requirements.
A finer adjustment down to 1-year steps is allowed by a special control complex:
In the upper part of the screen there is a double slider and a start-stop block.
- The lower slider allows to influence the start and end value of the display period in 10-year steps. The upper slider allows to change the display period freely in 10-year steps.
- The start-stop block contains buttons to change the reference year in 1-year steps (bottom) and elements to automatically scroll the display period forward or backward (1-year steps) or to stop the automatic scroll (top). The frequency of the automatic run-through can finally be influenced by 5 further buttons "Year runner - dwell time" below between the 1-year buttons, from quite fast (is the default, 400ms) to quite slow (2400ms).
Note: If you want to adjust the dwell time to your own time requirements, you can also overwrite the values once as described above in the JavaScript coding parms.js - LINloop_Speed.
When changing the reference time, such nodes whose reference year is outside the period are automatically removed and also inserted again, if the limits (start year of the display period - current reference time) include the reference year.
Another addition to the Lineage origin concerns the design of the option to delimit subsets of nodes by family names. One can call up a comprehensive list of family names, optionally sorted by frequency or alphabetically, and within the total set also delimitable by initial letter. By means of checkboxes names can be selected and deposited as filter criterion. It is also possible to create several filter definitions and to switch between them in the further course. As with the reference year, all nodes whose name criterion does not correspond to the active filter are removed from the display. The relevant name criterion results according to the default of the name scheme (see above), e.g. if SoundDM is set, all nodes corresponding to the SoundDM value of a name in the filter will be displayed, even if their plain name differs from it (one selects 'Mayer' and gets 'Meier', 'Meyer', 'Meir' etc. in addition).
By clicking on the checkbox "with partners", in addition to the persons selected via the active filter, the respective assigned spouses are also included in the display. The representing nodes are then displayed with reduced size.
At the bottom of the screen, the current reference time and the number of active and hidden nodes are displayed. With regard to the hidden nodes, no further differentiation is made, i.e. no distinction is made as to whether the name filter or the period filter has been applied.
Finally, there are action buttons at the top right of the screen:
Using the top button - a printer icon - the current rendering will be exported as SVG.
The other buttons are related to the technical platform that generates the representation. As mentioned, this is a D3js force simulation.
The idea behind this is that a representation results from the interplay of attractive and repulsive forces, which act iteratively on the nodes in a large number of passes. Initially, the energy level of the forces is high and decreases from run to run. The display is not generated after each run but after a fixed period of time. If the energy level is high, the nodes can change their location abruptly from one screen update to the next. If the level is lower, the location changes are much less pronounced, so that you may only notice a certain "tremor". Once the energy level drops below the final value the iteration loop is terminated.
From TAM the feature was taken over that at energy level "0" the display tree is underlaid with a kind of map whose contour lines correspond to annual values - the T in TAM. The second button from the top - a stop symbol - alternately sets the energy level to "0" - the map appears - or back to the previous value - the map disappears again. (This function is not effective in the group display).
Each simulation starts with a relatively compact agglomeration of all nodes. Each node acts on its environment. If a dataset contains many nodes, it is quite likely that at the end of the iteration cycle the distribution of the nodes is not yet really balanced due to mutual quasi blockades. An iteration cycle contains about 300 runs, possibly less if a final energy value > "0" is given. The third button - a thermometer symbol - raises the current energy level by 0.1 each time it is pressed (the maximum value is 1), so that a further sequence of iterations is triggered. If the number of nodes is large, this will result in further shifts, if the number of nodes is rather low (a few 100s at the most), the display will not change any more, because a stable state of equilibrium of the acting forces has probably been reached.
Under the action buttons the current "alpha" value is displayed for information, it corresponds to the respective energy level, scaled up from the range 0-1 to 0-100 for better recognizability. If the value does not change anymore, the iteration cycle is finished. In the tree display, the end value is currently 0.05, in the timeline 0.01 and in the groups 0.001. The D3js procedure is comprehensibly computationally expensive, rounding errors inevitably occur, therefore the displayed "alpha" values are not shown accordingly smooth, but with various decimal places.
Finally, it should be mentioned that the display supports zoom and pan. By clicking in the plot and then dragging, the whole plot can be moved - PAN. With the mouse wheel you can change the size of the view - ZOOM. ZOOM also takes into account the position of the mouse pointer, a ZOOM point outside the center of the display will cause the whole image to shift. You can restore the initial situation with a "Center" button (for easier orientation, a target cross is underlaid on the display as a whole). Scaling and temporary reference point of the representation are displayed below the "Center" button as an info box.
The ZOOM limits are set very wide, so that the display can be controlled by this alone. In addition, the size of the viewbox (the technical screen element in which the display is anchored) can be influenced in several steps. In the initial state, the viewbox size is set to 6x6 (6000x6000 pixels), so that trees with up to 250 nodes can be displayed quite clearly. If the number of nodes is higher, it is likely that the overall view will only be obtained by intensive ZOOM. To make things easier, the viewbox can be enlarged and reduced by 2 steps - if the viewbox is set to 9x9 or 12x12, the nodes are displayed correspondingly smaller, but the overall view is obtained even without ZOOM. Alternatively, 4x4 and 2x2 can also be set, in which case the nodes are significantly larger and the accompanying text in the display is also easily recognizable.
The viewbox setting is independent of the actual view, but the ZOOM and PAN settings are maintained independently for each view - so when the view is changed, the displayed (info box) values may differ from the effective values.
If the mouse pointer hovers over a node, the underlying information is displayed as a tooltip. Some of this information is shown as accompanying text directly in the display, such as the name in the Tree View or the order criteria and numbers in the other views.
When clicking on a node, its size is doubled. If you drag it to another position in this state (DRAG-n-DROP), it is fixed there, is no longer subject to the iteration process and, as a side effect, also stabilizes the positions of the other nodes connected to it via links. Clicking on the node again removes the fixation, the size is reset to the regular value and the node follows the simulation effects again.
You can also fix a node by double-clicking on it without dragging it to a different position; it will be highlighted as described and released with a single click.
In the Tree View, people and relationships / nodes and their links / nodes and links are the central element, the display focuses on the individual level.
In contrast, the other two views focus on higher-level aspects.
The nodes are differentiated by gender—women as circles, men as squares. The colors vary according to family name.
The links between parents and children are directed, light blue for male descendants, pink for female descendants ... (sorry). The links between the parents are undirected, interrupted, and kept in a yellow-green color variation.
 |
 |
In connection with the treatment of the family names - various encodings per SoundEx - it was already mentioned that the clusters view focuses on the names. The persons are grouped according to the family names, the name groups are the primary display element. There are 2 display variants, the initial view is the "Heap View", where the name groups are shown as a force simulation. The size corresponds with the number of persons, which lead in each case the same name coding. The distribution of the groups results from the force algorithm. Alternatively, the groups can also be shown in the "Grid View", they are then displayed with fixed positions in a grid, the assigned positions result from the 1st letter of the surname - 'A' is at the top left, 'Z' at the bottom right. The grid size corresponds in some way to the number of groups, but is basically quite generously dimennsioned. At present, the different group radii are not taken into account in the position determination, therefore groups of above-average size can overlap with surrounding groups - to reduce this effect, the largest possible distances between the groups are aimed at.
The single persons of a group are displayed after a RIGHT-click. These person nodes are subject to force simulation, so the display will be turbulent at first. Another RIGHT-click will hide the person nodes again. If the person node view is active, the group node is locked and highlighted.
The display of the group nodes changes as with the RIGHT-click also with the DRAG-n-DROP, the border width is doubled and the color changes to a strong purple. In the Tree View, a single mouse click terminates the DRAG-n-DROP state, the node is then more or less automatically returned to its relative starting position by the force simulation. Not so in the group grid view, here only a DOUBLE-click on the group node brings it back to its grid place. The Group Heap View handles this differently, if it was a DRAG-n-DROP operation, the single click unlocks the node and it rejoins the simulation. If the person view is active, the display changes first and the node reacts to the simulation again, but at the end of the force run (at the latest after a ReHeat) locking and highlighting occur again. If you end the person view, locking and highlighting will remain for the time being and must be explicitly ended with a single click.
Reason: Every state change affects the underlying simulation. Removing the person nodes and simultaneously unlocking the group node leads to a rather chaotic development; decoupling noticeably reduces the resulting turbulence.
Unlike in the other two views, 'Simulation Stop' only causes the force simulation to stop, the time map is not activated.
This view focuses on the temporal aspect. The persons are grouped by year of birth, the time groups are shown distributed over the time bar. The length of the timeline corresponds to the range of birth years. At the bottom of the screen there is an additional control to navigate in the display. In the initial state, the display is arranged so that the center point corresponds to the center of the time beam. The buttons of the control element can be used to position on the respective extreme points (1st and last group) as well as on the time points of the respective closest groups on the left and right (-1 and +1, respectively) or to move back to the center. The 'Left'- and 'Right'-1 step buttons are equipped with auto-repeat, if you click on the areas for a longer time, the groups are changed continuously, if the click stops, the auto-repeat also stops.
When jumping to a particular group, the corresponding relative position on the timeline is marked with the respective year, the group itself is highlighted and the entire display is shifted so that the group is shown in the center of the screen.
A time group is displayed as a vertical bar, the horizontal position corresponds to the relative position on the timeline. The vertical extent corresponds to the number of persons in the group.
The person nodes are permanently displayed in the view and are subordinated to the time groups, the horizontal position corresponds to the time group, the vertical position results from the sequence when building the groups. By DRAG-n-DROP a person node can be moved, but when finished it returns to the starting position.
The person nodes are equipped with additional properties:
- A CTRL-click/CTRL-click on a node displays the information otherwise listed in the tooltip in a permanent element in the display background, the node itself is highlighted at its position. The info element is closed again by another CTRL-click on the node or by a single click in the info element. If several nodes are activated one after the other in this way, the info elements are displayed in several rows from left to right in the sequence in which they were created. If an element is closed, the following elements move up immediately.
- A DOUBLE-click on a node shows the corresponding relations/connections/links, furthermore the node is enlarged and highlighted in color as well as placed clearly above the group bar. This function allows to display lineages over time.
The time group bars also have an additional property:
- A CTRL-click on a bar will immediately shift the entire display so that this bar is positioned in the center of the screen (analogous to the stepwise shift via the control buttons) and the associated time marker will be displayed on the timeline.
This module requires webtrees version 2.2.x. This module has the same general requirements as named for Webtrees overall webtrees#system-requirements.
This section describes how to install this module.
- Download Latest Release.
- Unzip to the
webtrees/modules_v4directory on the web server. - Occasionally rename the folder to
huhwt-wtlin. If the folder already exists, it can be easily overwritten.
For the latest version, simply replace the existing huhwt-wtlin files with those from the latest release.
You can help with the translation of this module. The po/mo system is used in the PHP part. The javascript functions have their own independent i18n implementation. Updated translations will be distributed with the next version of the module.
All texts and messages are available in English, German, Dutch, Catalan and Spanish.
Issues: You can report bugs by filing an issue in this GitHub repository.
- Lineage Ben Garvey https://github.com/bengarvey/lineage / Jens-Peter Stern https://knoten.familie-stern.de/
- TAM R.Preiner and team at the University of Graz, who published the method in his repository https://github.com/rpreiner/tam.
- Slider John Walley and contributors https://github.com/johnwalley/d3-simple-slider
- i18n Simon Rodwell and contributors https://github.com/roddeh/i18njs
- Translation NL : TheDutchJewel
- Translation CA/ES Bernatbanyuls
- D3.js : D3js.org - D3 on Github - Observable masses of examples
This program is open source, governed by the terms of the GNU General Public License, either version 3 of the License, or (at your option) any later version.
You should have received a copy of the GNU General Public License with this program, if not see http://www.gnu.org/licenses/.
Remark: This text was produced with the generous assistance of DeepL.