Difference between revisions of "Addon:DescendantSpaceTree"
From Gramps
m (→See also) |
(→Issues) |
||
| (32 intermediate revisions by 4 users not shown) | |||
| Line 2: | Line 2: | ||
[[File:DescendantSpaceTree-WebPage-Addon-example-60.png|thumb|right|450px|DescendantSpaceTree Web Page example output]] | [[File:DescendantSpaceTree-WebPage-Addon-example-60.png|thumb|right|450px|DescendantSpaceTree Web Page example output]] | ||
| − | The {{man label|Descendant Space Tree}} addon creates an | + | The {{man label|Descendant Space Tree}} addon creates an graphical space efficient display with interactive navigation on a web page, even with large families. |
;Features | ;Features | ||
| Line 16: | Line 16: | ||
== Usage == | == Usage == | ||
| − | The {{man label|Descendant Space Tree}} report is available from the menu {{man menu|Reports > Web Pages > Descendant Space Tree...}} | + | The {{man label|Descendant Space Tree}} report is available from the menu {{man menu|Reports > Web Pages > Descendant Space Tree...}} choose your Center Person and select {{man button|OK}} to create the report. |
{{-}} | {{-}} | ||
| − | + | ||
===== Report Options ===== | ===== Report Options ===== | ||
| − | [[File:DescendantSpaceTree-ReportOptions-60.png|thumb|right|450px|DescendantSpaceTree - Web Pages - Addon - "DescendantSpaceTree Options" defaults]] | + | [[File:DescendantSpaceTree-ReportOptions-60-110.png|thumb|right|450px|DescendantSpaceTree - Web Pages - Addon - "DescendantSpaceTree Options" defaults]] |
On the {{man label|Report Options}} tab: | On the {{man label|Report Options}} tab: | ||
* {{man label|Center Person:}} defaults to the active person. | * {{man label|Center Person:}} defaults to the active person. | ||
| + | ** {{man button|Select a different person}} selector button | ||
* {{man label|Include Generations:}} <code>20</code> (default) - The number of generations to include in the tree. | * {{man label|Include Generations:}} <code>20</code> (default) - The number of generations to include in the tree. | ||
* {{man label|Branch to expand when duplicated:}} In case of inter-family marriages, select the line to expand further descendants from the common ancestor: | * {{man label|Branch to expand when duplicated:}} In case of inter-family marriages, select the line to expand further descendants from the common ancestor: | ||
| − | ** Patriarchal Line (default) - choose the branch that contains the common ancestor who is male to expand. | + | ** '''Patriarchal Line (Male ancestor)''' (default) - choose the branch that contains the common ancestor who is male to expand. |
| − | ** Matriarchal Line - choose the branch that contains the common ancestor who is female to expand. | + | ** ''Matriarchal Line'' - choose the branch that contains the common ancestor who is female to expand. |
* {{man label|Maximum display birth year:}} <code>1900</code> (default) - Limits the display of dates for persons born after this year. | * {{man label|Maximum display birth year:}} <code>1900</code> (default) - Limits the display of dates for persons born after this year. | ||
| + | * {{man label|Theme preference:}} Generate the web page Space Tree graph canvas with a specific theme: | ||
| + | ** '''Dark theme''' (default) - use dark background for graph canvas. | ||
| + | ** ''Light theme'' - use a light background for graph canvas. | ||
* {{man label|Destination:}} defaults to the user home directory. The destination directory for the generated HTML file. | * {{man label|Destination:}} defaults to the user home directory. The destination directory for the generated HTML file. | ||
** {{man button|The destination path for generated files}} button | ** {{man button|The destination path for generated files}} button | ||
* {{man label|Destination File:}} <code>DescendantSpaceTree.html</code> (default) The destination HTML file name. | * {{man label|Destination File:}} <code>DescendantSpaceTree.html</code> (default) The destination HTML file name. | ||
| + | * {{checkbox|1}}{{man label|Open with default viewer}} - Opens the generated web page with user's default web browser. | ||
{{-}} | {{-}} | ||
=== Web page usage === | === Web page usage === | ||
| − | + | [[File:DescendantSpaceTree-WebPage-Addon-control-closeup-search-example-60.png|thumb|right|450px|Descendant Space Tree Web Page example output - showing search and both the reset and help buttons ]] | |
| + | [[File:DescendantSpaceTree_Browser_Help-60-110.png|thumb|right|450px|DescendantSpaceTree Web Page Help popup]] | ||
The generated HTML file <code>DescendantSpaceTree.html</code> can be published to a web server, or simply opened locally with a web browser or file explorer (Edge, Chrome, Safari, Firefox, Opera, etc.) | The generated HTML file <code>DescendantSpaceTree.html</code> can be published to a web server, or simply opened locally with a web browser or file explorer (Edge, Chrome, Safari, Firefox, Opera, etc.) | ||
| − | The person chosen as the | + | The person chosen as the {{man label|Center Person:}} option will be displayed in yellow, and immediate descendants are expanded. Basic information about the selected person is shown on the left. |
| − | Depending on the | + | Depending on the {{man label|Maximum display birth year:}} option, dates may be excluded from the basic information. |
| − | Clicking on any of the displayed person nodes will change focus, and close any other currently open branch. | + | Clicking on any of the displayed person nodes will change focus, and close any other currently open branch. The immediate descendants of the focused person will be colored to indicate the number of immediate descendants. The deeper the hue of coloring indicates a greater number of immediate descendants. |
The entire graph within the canvas can be re-positioned by clicking and holding on the canvas, followed by dragging. | The entire graph within the canvas can be re-positioned by clicking and holding on the canvas, followed by dragging. | ||
| − | A | + | A {{man button|🔍 Search}} box in the top right side of the window can be used to quickly focus on a person, including any persons not currently displayed. Any part of a name can be searched, as well as the Gramps Database ID. At least three characters are required before the search displays results. The list of search results can be scrolled with a mouse wheel or touch pad, or up and down arrow keys. Click on a person in the search to focus immediately on that person, or press the Escape key to cancel the search. Persons found in the search that include a plus sign '''+''' indicate that person is a spouse of a descendant. |
| − | + | Selecting the {{man button|⟳ Reset}} button displays the graph focused back on the original starting person and graph position. | |
| − | The | + | The descendant graph is reset to the starting person whenever the browser window is resized. Resizing or toggling full screen {{man button|F5}} before navigating the descendant tree to is recommended. |
| + | The {{man button|？ Help}} button will display usage for the viewer. Click either the {{man button|X - Close}} button or press the {{man button|Escape}} key to close the help window. | ||
{{-}} | {{-}} | ||
=== Duplicate branches from inter-family marriages === | === Duplicate branches from inter-family marriages === | ||
| − | In the case of an inter-family marriages (i.e., such of that of a marriage of cousins), there would otherwise be two branches of descendants. DescendantSpaceTree only expands the descendants from such families in one branch, while the other branch is pruned. The choice is made by the setting of the | + | In the case of an inter-family marriages (i.e., such of that of a marriage of cousins), there would otherwise be two branches of descendants. DescendantSpaceTree only expands the descendants from such families in one branch, while the other branch is pruned. The choice is made by the setting of the {{man label|Branch to expand when duplicated:}} option. During report generation, the common ancestor of the two parents is found. The branch that contains the selected line (Patriarchal or Matriarchal) will be further expanded. |
An extra button will be displayed in these cases in the bottom left of the window. When the branch is that of the selected line, the button will | An extra button will be displayed in these cases in the bottom left of the window. When the branch is that of the selected line, the button will | ||
navigate to the same person in the alternate branch. The pruned branch will display immediate descendants in blue, indicating that they can be expanded in the primary branch. Likewise, if navigating to a descendant via the pruned branch, a button will allow navigation back to the expanded branch. | navigate to the same person in the alternate branch. The pruned branch will display immediate descendants in blue, indicating that they can be expanded in the primary branch. Likewise, if navigating to a descendant via the pruned branch, a button will allow navigation back to the expanded branch. | ||
| − | |||
{{-}} | {{-}} | ||
==See also== | ==See also== | ||
* [https://gramps.discourse.group/t/descendantspacetree-addon-initial-development/7764 DescendantSpaceTree addon - initial development] announcement 2025/05/31 - Gramps Discourse forum. | * [https://gramps.discourse.group/t/descendantspacetree-addon-initial-development/7764 DescendantSpaceTree addon - initial development] announcement 2025/05/31 - Gramps Discourse forum. | ||
| + | ** Descendant Space Tree is based on the original paper [https://www.cs.umd.edu/projects/hcil/spacetree/ SpaceTree: a novel node-link tree browser] by the Human-Computer Interaction Lab (HCIL) at the University of Maryland, USA | ||
* [[Addon:DenominoViso|DenominoVisio...]] (addon) - Almost identical report. | * [[Addon:DenominoViso|DenominoVisio...]] (addon) - Almost identical report. | ||
* [[Addon:D3_Ancestral_and_Descendant_Charts#Ancestral_Collapsible_Tree|Ancestral Collapsible Tree...]] (D3 addon) | * [[Addon:D3_Ancestral_and_Descendant_Charts#Ancestral_Collapsible_Tree|Ancestral Collapsible Tree...]] (D3 addon) | ||
| Line 71: | Line 78: | ||
{{-}} | {{-}} | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==Issues== | ==Issues== | ||
* Help button goes to http://gramps-project.org/wiki/index.php?title=Gramps_6.0_Wiki_Manual_-_Reports#Descendant_Space_Tree | * Help button goes to http://gramps-project.org/wiki/index.php?title=Gramps_6.0_Wiki_Manual_-_Reports#Descendant_Space_Tree | ||
| + | * Feature request: Allow selection of canvas background color, perhaps other colors. | ||
| + | * Feature request: Backport to Gramps 5.2 | ||
| + | * Feature request: Books mode compatibility | ||
| + | * Feature request: Automatically resize the space tree graph when browser window is resized. | ||
| + | |||
| + | If you have trouble displaying the report on your local computer see the following: | ||
| + | * [[Addon:D3_Ancestral_and_Descendant_Charts#Charts_appear_without_content_when_using_local_mode|Charts appear without content when using local mode]] | ||
[[Category:Addons]] | [[Category:Addons]] | ||
Latest revision as of 01:40, 20 June 2025
|
This is a Third-party Addon. The Addon/Plugin system is controlled by the Plugin Manager. Please use carefully on data that is backed up, and help make it better by reporting any issues to the bug tracker. |
The Descendant Space Tree addon creates an graphical space efficient display with interactive navigation on a web page, even with large families.
- Features
- Space Tree representation allows users to focus on descendant lines back to the starting ancestor.
- Clicking on a person node expands immediate descendants and updates basic information about that person (parents, descendant count, spouses, dates).
- A search box to find a descendant or spouse by any part of a name, clicking on a search result immediately focuses on that person.
- Click-hold-drag anywhere on the canvas will reposition the tree.
- A reset button to reposition the graph back to the starting person and position.
- A help button to display usage.
- Branch pruning in the case of inter-family marriages, with navigation to alternate branch.
- The web page is created as a single HTML file with no external dependencies.
Contents
Usage
The Descendant Space Tree report is available from the menu Reports > Web Pages > Descendant Space Tree... choose your Center Person and select OK to create the report.
Report Options
On the Report Options tab:
- Center Person: defaults to the active person.
- Select a different person selector button
- Include Generations:
20(default) - The number of generations to include in the tree. - Branch to expand when duplicated: In case of inter-family marriages, select the line to expand further descendants from the common ancestor:
- Patriarchal Line (Male ancestor) (default) - choose the branch that contains the common ancestor who is male to expand.
- Matriarchal Line - choose the branch that contains the common ancestor who is female to expand.
- Maximum display birth year:
1900(default) - Limits the display of dates for persons born after this year. - Theme preference: Generate the web page Space Tree graph canvas with a specific theme:
- Dark theme (default) - use dark background for graph canvas.
- Light theme - use a light background for graph canvas.
- Destination: defaults to the user home directory. The destination directory for the generated HTML file.
- The destination path for generated files button
- Destination File:
DescendantSpaceTree.html(default) The destination HTML file name. - Open with default viewer - Opens the generated web page with user's default web browser.
Web page usage
The generated HTML file DescendantSpaceTree.html can be published to a web server, or simply opened locally with a web browser or file explorer (Edge, Chrome, Safari, Firefox, Opera, etc.)
The person chosen as the Center Person: option will be displayed in yellow, and immediate descendants are expanded. Basic information about the selected person is shown on the left.
Depending on the Maximum display birth year: option, dates may be excluded from the basic information.
Clicking on any of the displayed person nodes will change focus, and close any other currently open branch. The immediate descendants of the focused person will be colored to indicate the number of immediate descendants. The deeper the hue of coloring indicates a greater number of immediate descendants.
The entire graph within the canvas can be re-positioned by clicking and holding on the canvas, followed by dragging.
A 🔍 Search box in the top right side of the window can be used to quickly focus on a person, including any persons not currently displayed. Any part of a name can be searched, as well as the Gramps Database ID. At least three characters are required before the search displays results. The list of search results can be scrolled with a mouse wheel or touch pad, or up and down arrow keys. Click on a person in the search to focus immediately on that person, or press the Escape key to cancel the search. Persons found in the search that include a plus sign + indicate that person is a spouse of a descendant.
Selecting the ⟳ Reset button displays the graph focused back on the original starting person and graph position.
The descendant graph is reset to the starting person whenever the browser window is resized. Resizing or toggling full screen F5 before navigating the descendant tree to is recommended.
The ？ Help button will display usage for the viewer. Click either the X - Close button or press the Escape key to close the help window.
Duplicate branches from inter-family marriages
In the case of an inter-family marriages (i.e., such of that of a marriage of cousins), there would otherwise be two branches of descendants. DescendantSpaceTree only expands the descendants from such families in one branch, while the other branch is pruned. The choice is made by the setting of the Branch to expand when duplicated: option. During report generation, the common ancestor of the two parents is found. The branch that contains the selected line (Patriarchal or Matriarchal) will be further expanded.
An extra button will be displayed in these cases in the bottom left of the window. When the branch is that of the selected line, the button will
navigate to the same person in the alternate branch. The pruned branch will display immediate descendants in blue, indicating that they can be expanded in the primary branch. Likewise, if navigating to a descendant via the pruned branch, a button will allow navigation back to the expanded branch.
See also
- DescendantSpaceTree addon - initial development announcement 2025/05/31 - Gramps Discourse forum.
- Descendant Space Tree is based on the original paper SpaceTree: a novel node-link tree browser by the Human-Computer Interaction Lab (HCIL) at the University of Maryland, USA
- DenominoVisio... (addon) - Almost identical report.
- Ancestral Collapsible Tree... (D3 addon)
- Descendant Indented Tree... (D3 addon)
Issues
- Help button goes to http://gramps-project.org/wiki/index.php?title=Gramps_6.0_Wiki_Manual_-_Reports#Descendant_Space_Tree
- Feature request: Allow selection of canvas background color, perhaps other colors.
- Feature request: Backport to Gramps 5.2
- Feature request: Books mode compatibility
- Feature request: Automatically resize the space tree graph when browser window is resized.
If you have trouble displaying the report on your local computer see the following:
