diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..fde62050 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,50 @@ +name: docs + +# Build the MkDocs Material site and deploy it to GitHub Pages. +# Requires: Settings -> Pages -> Source: "GitHub Actions" (one-time, manual). + +on: + push: + branches: [main] + paths: + - docs/** + - mkdocs.yml + - .github/workflows/docs.yml + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment; don't cancel an in-progress one. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + cache-dependency-path: docs/requirements.txt + - run: pip install -r docs/requirements.txt + - run: mkdocs build --strict + - uses: actions/configure-pages@v5 + - uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index cefc1e00..a8746dcb 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,5 @@ test.py .venv/ # generated by setuptools-scm at build time PyReconstruct/_version.py +# MkDocs build output +site/ diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 505438ec..1a27f449 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -16,7 +16,7 @@ The University of Texas at Austin) and the in-app **Help ▸ Shortcuts list**. > > > 📸 *Screenshot: short description of what to capture.* > -> Contributions of screenshots are welcome — see [CONTRIBUTING.md](../CONTRIBUTING.md). +> Contributions of screenshots are welcome — see [CONTRIBUTING.md](https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md). > **Shortcuts.** Key combinations shown here are the **defaults**. Almost all of > them are rebindable under **Help ▸ Shortcuts list** (press `?`). A few menu @@ -99,7 +99,7 @@ PyReconstruct `pip` pulls in the runtime dependencies (PySide6, VTK, vedo, NumPy, SciPy, scikit-image, shapely, trimesh, zarr, and others). For a full development setup (conda environment, tests, code layout), see -[CONTRIBUTING.md](../CONTRIBUTING.md). +[CONTRIBUTING.md](https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md). ### Launching the app @@ -923,5 +923,5 @@ the original **Reconstruct** by John C. Fiala. This distribution is independently developed and maintained by **Dusten Hubbard** (Kristen Harris Lab, **The University of Texas at Austin**). See the -[README](../README.md) for provenance, performance notes, and citation details, and -[CONTRIBUTING.md](../CONTRIBUTING.md) to help improve PyReconstruct. +[README](https://github.com/dustenhubbard/PyReconstruct/blob/main/README.md) for provenance, performance notes, and citation details, and +[CONTRIBUTING.md](https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md) to help improve PyReconstruct. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..ec2d021c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,48 @@ +# PyReconstruct + +PyReconstruct is an open-source desktop application for tracing, annotating, and +3D-reconstructing serial-section and volume electron-microscopy (EM) data. It is +the modern, actively maintained successor to *Reconstruct*. + +This site documents an independently developed and maintained distribution of +PyReconstruct. It tracks the upstream +[SynapseWeb/PyReconstruct](https://github.com/SynapseWeb/PyReconstruct) project +and builds on it with 3-4x faster open and refresh on large series, one-click +installers, an in-app updater, and ongoing user-interface modernization. + +## Who it's for + +Neuroscientists and EM researchers who trace neural structures across stacks of +serial sections - segmenting objects, aligning sections, measuring morphology, +and building 3D reconstructions of cells, organelles, and synapses from +volume-EM datasets. It reads and writes the `.jser` series format and handles +large autosegmented series with hundreds of thousands of traces. + +## Install + +Download a one-click build (Windows `.exe`, macOS `.dmg`, or Linux installer) +from +**[Releases](https://github.com/dustenhubbard/PyReconstruct/releases)** - no +Python required. Developers can install from source with `pip` or `uv`. + +Full instructions, including the macOS Gatekeeper step and the in-app updater, +are in the [User Guide](USER_GUIDE.md#1-installing-pyreconstruct). + +## Where to go next + +- **[User Guide](USER_GUIDE.md)** - install, open a series, the tracing tools, + data lists, alignment, 3D reconstruction, and backups. +- **[Performance](performance.md)** - benchmarks for the fork's speed work. +- **[Developing with uv](DEV_UV.md)** - the uv-based development workflow. +- **[Contributing](https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md)** + - dev setup, branch/commit conventions, tests, and the PR process. +- **[Source code](https://github.com/dustenhubbard/PyReconstruct)** and + **[issues](https://github.com/dustenhubbard/PyReconstruct/issues)** on GitHub. + +## Citation + +PyReconstruct was developed in the Kristen Harris Lab at **The University of +Texas at Austin** and introduced in *PNAS* (2025), +[doi:10.1073/pnas.2505822122](https://doi.org/10.1073/pnas.2505822122). See the +[README](https://github.com/dustenhubbard/PyReconstruct/blob/main/README.md) +for full provenance, performance notes, and citation details. diff --git a/docs/performance.md b/docs/performance.md new file mode 100644 index 00000000..2998000b --- /dev/null +++ b/docs/performance.md @@ -0,0 +1,42 @@ +# Performance + +This distribution is significantly faster than the upstream it forked from on the +open and refresh paths that dominate day-to-day work on large series - **up to +4.19x faster** to open and refresh a series, with **exact geometry equivalence** +(the speedup is not from skipped work). + +The wins are algorithmic and single-threaded (NumPy-vectorized trace geometry, +deferred Feret-diameter computation, NumPy point mapping, orjson-backed `.jser` +I/O, and scoped object operations), so they help every machine and +disproportionately help the large autosegmented series that were previously near +unusable. + +## Headline results + +Median of repeated runs, upstream origin to this fork: + +| Series | Size | Traces | Open (origin -> fork) | Open+Refresh speedup | +|---|--:|--:|---|--:| +| crop_1 | 6 MB | 2209 | 1.115 -> 0.325s | 3.44x | +| ZGBJY | 7 MB | 2511 | 1.733 -> 0.409s | 4.19x | +| crop_2 | 92 MB | 27525 | 18.87 -> 4.78s | 3.84x | +| GBSFW | 127 MB | 61121 | 28.32 -> 8.76s | 3.18x | +| NVWXP | 187 MB | 83126 | 38.79 -> 12.04s | 3.2x | +| crop_3 | 312 MB | 89388 | 63.24 -> 16.95s | 3.69x | +| crop_4 | 701 MB | 204622 | 143.14 -> 48.52s | 3.29x | +| crop_ROIsmall | 1400 MB | 492574 | 288.27 -> 100.10s | 3.11x | + +Per-series geometry equivalence (section, object, and trace counts, plus summed +area / length / radius) is exact across the board. + +## Full report and method + +The complete report - including the equivalence checks, per-commit attribution, +hardware and dependency versions, and the measurement methodology - and the +reproducible benchmark harness live in the repository: + +- **[benchmarks/REPORT.md](https://github.com/dustenhubbard/PyReconstruct/blob/main/benchmarks/REPORT.md)** + - the full report. +- **[benchmarks/](https://github.com/dustenhubbard/PyReconstruct/tree/main/benchmarks)** + - the harness (`harness.py`, `orchestrate.py`, `build_report.py`) and raw + results. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..bca32c75 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +# Documentation build dependencies (MkDocs Material docs site). +# mkdocs-material pulls in mkdocs, pymdown-extensions, and the search plugin. +mkdocs-material==9.7.6 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..4bfa1af5 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,52 @@ +site_name: PyReconstruct +site_description: >- + Tracing, annotation, and 3D reconstruction for serial-section and volume + electron microscopy. +site_url: https://dustenhubbard.github.io/PyReconstruct/ +repo_url: https://github.com/dustenhubbard/PyReconstruct +repo_name: dustenhubbard/PyReconstruct +edit_uri: edit/main/docs/ +docs_dir: docs + +theme: + name: material + icon: + repo: fontawesome/brands/github + features: + - navigation.instant + - navigation.top + - navigation.sections + - search.suggest + - content.code.copy + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: teal + accent: teal + toggle: + icon: material/weather-night + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: teal + accent: teal + toggle: + icon: material/weather-sunny + name: Switch to light mode + +plugins: + - search + +markdown_extensions: + - toc: + permalink: true + - pymdownx.highlight + - pymdownx.superfences + +nav: + - Home: index.md + - User Guide: USER_GUIDE.md + - Performance: performance.md + - Developing with uv: DEV_UV.md + - Contributing: https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md + - Security: https://github.com/dustenhubbard/PyReconstruct/blob/main/SECURITY.md