Metadata-Version: 2.4
Name: homlab-editor
Version: 0.1.3
Summary: A pygame-based editor and Pillow renderer for HomLab JSON diagrams.
Author: Homology Lab
License-Expression: MIT
Keywords: homlab,homology,editor,pygame,pillow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame>=2.5
Requires-Dist: Pillow>=10.0
Requires-Dist: filelock>=3.0
Requires-Dist: segment-intersection-2d>=0.1.0
Dynamic: license-file

# 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](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.
- 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:

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

For a normal package installation:

```bash
python -m pip install homlab-editor
```

## Run The Editor

Open or create a HomLab JSON file:

```bash
homlab-editor data/example.json
```

The module entry point is equivalent:

```bash
python -m homlab_editor data/example.json
```

Open without allowing topology edits:

```bash
homlab-editor data/example.json --readonly
```

Open in read-only crossing-pick mode:

```bash
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:

```bash
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:

```bash
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.

## Python API

```python
from homlab_editor import HomologyLabEditor

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

Static image rendering API:

```python
from homlab_editor.static_image import render_homlab_file

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

## Documentation

- [English user manual](docs/user-guide.md)
- [Chinese user manual](docs/user-guide.zh-CN.md)
- [Software algorithm document](docs/algorithm.md)
- [Static image rendering](docs/static-rendering.md)
- [File format](docs/file-format.md)
- [Python API](docs/api.md)
- [Development and packaging](docs/development.md)
- [Documentation index](docs/index.md)

## Build

Build the source distribution and wheel:

```bash
python -m pip install build
python -m build
```

Build artifacts are written to `dist/`.
