HomLab Editor

HomLab Editor is a pygame-based graphical editor for HomLab JSON diagrams, with a Pillow-based static renderer for producing image files without opening the editor window. It edits genus handles, border handles, ordinary nodes, edges, crossings, and the saved view parameters directly in the JSON file.

Chinese manual: docs/user-guide.zh-CN.md

Features

• Creates a default HomLab JSON file when the target path does not exist.
• Adds, drags, deletes, and connects ordinary nodes in the graphical editor.
• Connects ordinary nodes to genus handles or border handles.
• Stores optional per-edge RGB colors while keeping older JSON files compatible.
• Adjusts genus count, view scale, window size, view center, and border spacing.
• Detects crossings between non-adjacent line segments and lets the user swap the crossing order by clicking a crossing.
• Supports read-only mode and a read-only crossing-pick mode for integration workflows.
• Saves through a soft file lock next to the JSON file.
• Provides command line entry points and a Python API.
• Renders JSON diagrams to static images with Pillow through homlab-render.

Installation

Python 3.9 or newer is required.

For local development:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

For a normal package installation:

python -m pip install homlab-editor

Run The Editor

Open or create a HomLab JSON file:

homlab-editor data/example.json

The module entry point is equivalent:

python -m homlab_editor data/example.json

Open without allowing topology edits:

homlab-editor data/example.json --readonly

Open in read-only crossing-pick mode:

homlab-editor data/example.json --pick-crossing data/selected-crossing.json

In crossing-pick mode the user can still move and scale the view, but cannot edit nodes, edges, genus count, border spacing, or crossing order. Clicking a crossing closes the editor and writes the selected edge pair and crossing coordinates to the output JSON file.

Static Rendering

Render a HomLab JSON file to an image without opening a pygame window:

homlab-render data/example.json data/example.png --size 1000

--size sets the square output width and height in pixels. Static rendering auto-fits the drawn content by default and does not draw the editor toolbar.

Use the saved JSON view instead of auto-fitting:

homlab-render data/example.json data/example.png --size 1000 --use-json-view

Basic Editing

Left-click empty canvas space to create a node. Hold and drag a node to move it. Light-click a node or a handle to enter drawing mode. In drawing mode, click empty space to create and connect another node while staying in drawing mode; click an existing node or handle to connect and return to free mode.

Right-click an ordinary node to delete it. Right-click a hit-testable ordinary node-to-node edge to delete it. Left-click an ordinary node-to-node edge to split it by inserting a node at the cursor. Click a crossing to swap which of the two crossing edges is drawn on top.

Use Edge_Color, then click an edge to enter RGB values. Use All_Color to apply one RGB color to every existing edge. Edges without a saved color field use the default black edge color.

Python API

from homlab_editor import HomologyLabEditor

editor = HomologyLabEditor("data/example.json", readonly=True)
editor.mainloop()

Static image rendering API:

from homlab_editor.static_image import render_homlab_file

render_homlab_file("data/example.json", "data/example.png", size=1000)

Documentation

• English user manual
• Chinese user manual
• Software algorithm document
• Static image rendering
• File format
• Python API
• Development and packaging
• Documentation index

Build

Build the source distribution and wheel:

python -m pip install build
python -m build

Build artifacts are written to dist/.