Skip to content

README.md

Latest commit

 

History

History
187 lines (131 loc) · 5.26 KB

README.md

File metadata and controls

187 lines (131 loc) · 5.26 KB

GedGraph

Generate genealogical charts from GEDCOM files using GraphViz.

Features

  • Pedigree Charts: Visualize ancestors of an individual
  • Relationship Charts: Find and visualize relationships between two individuals
  • Hourglass Charts: Show ancestors and descendants or split by parental lines
  • Bowtie Charts: Horizontal hourglass layout with left-right orientation
  • Smart Path Finding: Automatically finds the shortest relationship path using breadth-first search
  • Relationship Prioritization: Prefers blood relationships via male line, then female line, then half-blood relationships
  • Multiple Path Detection: Identifies when multiple equally short paths exist
  • Spouse Visualization: Shows spouses/partners alongside the direct bloodline
  • Marriage Status Indicators: Solid lines for married couples, dashed lines for unmarried couples
  • Flexible Date Handling: Uses birth/death dates with fallback to baptism/burial dates
  • Enhanced Name Formatting: Supports GEDCOM name components (prefix, title, given, surname, suffix)
  • Progress Feedback: Braille-spinner progress indicators with --verbose, --quiet, and --no-color options
  • GraphViz Output: Generates DOT files that can be rendered to various image formats

Prerequisites

  • Python 3.10+
  • GraphViz (dot command) installed on your system to render DOT files to images

Installation

pip install kimon-gedgraph

Development Setup

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Usage

Pedigree Chart

Generate a pedigree chart showing ancestors of an individual:

gedgraph pedigree family.ged @I10@ -o output.dot

Options:

  • -g, --generations: Number of generations to include (default: 4)

Example:

gedgraph pedigree family.ged @I10@ -g 5 -o pedigree.dot

Relationship Chart

Find and visualize the relationship between two individuals:

gedgraph relationship family.ged @I10@ @I20@ -o output.dot

Options:

  • -d, --max-depth: Maximum search depth (default: 50)

Example:

gedgraph relationship family.ged @I1@ @I50@ -d 15 -o relationship.dot

Hourglass Chart

Visualize ancestors and descendants or split by parental lines:

# Ancestors above, descendants below
gedgraph hourglass family.ged @I10@ -v descendants -o hourglass.dot

# Father's line above, mother's line below
gedgraph hourglass family.ged @I10@ -v ancestor-split -o hourglass.dot

Options:

  • -g, --generations: Number of generations in each direction (default: 4)
  • -v, --variant: Chart variant - ancestor-split or descendants (default: ancestor-split)

Bowtie Chart

Horizontal hourglass layout with left-right orientation:

# Ancestors left, descendants right
gedgraph bowtie family.ged @I10@ -v descendants -o bowtie.dot

# Father's line left, mother's line right
gedgraph bowtie family.ged @I10@ -v ancestor-split -o bowtie.dot

Options:

  • -g, --generations: Number of generations in each direction (default: 4)
  • -v, --variant: Chart variant - ancestor-split or descendants (default: ancestor-split)

Global Options

These flags must appear before the subcommand name:

# Suppress progress output
gedgraph --quiet pedigree family.ged @I10@ -o output.dot

# Show progress with timing
gedgraph --verbose relationship family.ged @I10@ @I20@ -o output.dot

# Disable colored output
gedgraph --no-color hourglass family.ged @I10@ -o output.dot
Flag Description
--verbose Show detailed progress with timing
-q, --quiet Suppress progress output
--no-color Disable colored output

Rendering DOT Files

Convert DOT files to images using GraphViz:

# PNG
dot -Tpng output.dot -o output.png

# PDF
dot -Tpdf output.dot -o output.pdf

# SVG
dot -Tsvg output.dot -o output.svg

Relationship Path Sorting

When multiple equally short paths exist between two individuals, GedGraph prioritizes them in this order:

  1. Full blood relationships via male line
  2. Full blood relationships via female line
  3. Half-blood relationships via male line
  4. Half-blood relationships via female line

The tool will generate charts for all paths of equal shortest length.

Example Output

The generated DOT files include:

  • Comments: Generation distance, path length, and relationship description
  • Color Coding:
    • Start individual (coral)
    • End individual (light blue)
    • Direct bloodline (light green)
    • Spouses/partners (light yellow)
  • Labels: Names with birth/death years in (YYYY - YYYY) format
  • Relationship Lines:
    • Solid arrows for parent-child relationships
    • Solid lines for married couples
    • Dashed lines for unmarried couples
  • Horizontal Alignment: Spouses are positioned next to their partners using rank constraints

Error Handling

GedGraph will exit with an error if:

  • The GEDCOM file doesn't exist
  • An individual ID is not found in the GEDCOM file
  • No relationship exists between two individuals (for relationship charts)

Development

See DEVELOPER.md for development setup and architecture details.

License

MIT