organella 0.1.0__tar.gz

organella-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+# A newer push cancels the run it superseded: the suite is the slow part of a review.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      # Both versions report, rather than the second being cancelled by the first's failure.
+      fail-fast: false
+      matrix:
+        # 3.11 is what pyproject asks for at the lowest; 3.12 is what it is developed on.
+        python: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # The report page is JavaScript, and parts of the suite run it through node: the way a
+      # report is read into the page, the geometry decoder, the merge arithmetic, the contact
+      # clustering, every query the geometry sections build, and every section drawn against a
+      # stub DOM. Without node those tests fail rather than skip.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # With the remote extra, so the manifest reader is installed rather than absent: a
+      # folder holding one source.json is an object too, and nothing else covers that path.
+      - name: Install
+        run: |
+          uv venv --python ${{ matrix.python }} .venv
+          VIRTUAL_ENV=$PWD/.venv uv pip install -e '.[remote,test]'
+
+      - name: Test
+        run: .venv/bin/python -m pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # Only the rules that catch a mistake rather than a preference: an undefined name, an
+      # unused import, a syntax error. The prose in this package is deliberate and the
+      # docstring and complexity rules would argue with it on every file.
+      - name: Ruff
+        run: uvx ruff check --select F,E9 src tests
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build
+        run: uv build
+
+      # The report page is a data file inside the package, and the suite reads it out of the
+      # source tree, so a wheel built without it would pass every test and still install a
+      # CLI whose `view` and `page` have nothing to open. Checked from a fresh environment,
+      # the way someone installing it gets it.
+      - name: The wheel carries the page, and the CLI can find it
+        run: |
+          unzip -l dist/*.whl | grep -q 'organella/report/organella_report.html'
+          uv venv --python 3.12 fresh
+          VIRTUAL_ENV=$PWD/fresh uv pip install dist/*.whl
+          page=$(fresh/bin/organella page)
+          test -f "$page"
+          echo "the installed CLI finds its page at $page"

organella-0.1.0/.github/workflows/deploy-pages.yml

@@ -0,0 +1,93 @@
+name: Deploy the report page to GitHub Pages
+
+# The report is read by one standalone HTML page: it loads a report.parquet in the browser
+# and draws every chart from it, so publishing it is a copy, not a build. It is served at
+# / and at /organella_report.html. The standalone prototype it grew out of keeps the URLs it
+# was published under (/stats_viewer.html, /mesh_viewer.html) so existing links work.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/organella/report/**'
+      - 'docs/**'
+      - '.github/workflows/deploy-pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+env:
+  # The last commit that changed the standalone prototype, before the package replaced it.
+  # Those files are frozen, so the site takes them straight out of history rather than
+  # keeping a copy in the tree.
+  PROTOTYPE_REF: 42c08030eca7b771844345c517d1e2cc904f4660
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # history back to PROTOTYPE_REF
+
+      # Node, because the page is checked before it is published: it is one file with no
+      # build step and nothing imports it, so this is the only thing standing between a
+      # typo in it and whoever opens the published copy.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install
+        run: |
+          uv venv --python 3.12 .venv
+          VIRTUAL_ENV=$PWD/.venv uv pip install -e '.[test]'
+
+      - name: Check the page reads a report and draws every section
+        run: .venv/bin/python -m pytest -q tests/test_report_page.py
+
+      - name: Publish the page
+        run: |
+          mkdir -p _site
+          page=$(.venv/bin/organella page)
+          cp "$page" _site/organella_report.html
+          cp "$page" _site/index.html
+
+      - name: Publish the imprint and the privacy policy
+        run: cp docs/impressum.html docs/privacy.html docs/_legal.css _site/
+
+      # Skipped rather than fatal when the commit is not there: a repository the history
+      # was not carried into still deploys, just without the prototype's URLs.
+      - name: Add the standalone prototype at its original URLs
+        run: |
+          if git cat-file -e "$PROTOTYPE_REF^{commit}" 2>/dev/null; then
+            git show "$PROTOTYPE_REF:stats_viewer.html" > _site/stats_viewer.html
+            git show "$PROTOTYPE_REF:mesh_viewer.html"  > _site/mesh_viewer.html
+          else
+            echo "::notice::$PROTOTYPE_REF is not in this repository; publishing without the prototype URLs"
+          fi
+
+      - name: Show what will be published
+        run: ls -lh _site
+
+      - 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

organella-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+# A tag is the trigger, so publishing is deliberate: `git tag v0.1.0 && git push --tags`.
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+# Nothing is granted by default; the publish job asks for the one token it needs.
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # The tag names the version that will be on PyPI forever, and pyproject names the
+      # version that is actually built. A mismatch means tagging v0.2.0 and shipping 0.1.0,
+      # or failing at the upload because 0.1.0 is already there.
+      - name: The tag and the version agree
+        if: github.ref_type == 'tag'
+        run: |
+          built=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
+          tagged="${GITHUB_REF_NAME#v}"
+          test "$built" = "$tagged" || {
+            echo "::error::tag $GITHUB_REF_NAME says $tagged, pyproject says $built"
+            exit 1
+          }
+          echo "releasing $built"
+
+      # A release should not be the first place a failure turns up, so the suite runs here
+      # too rather than trusting that CI ran on this commit.
+      - name: Test
+        run: |
+          uv venv --python 3.12 .venv
+          VIRTUAL_ENV=$PWD/.venv uv pip install -e '.[remote,test]'
+          .venv/bin/python -m pytest -q
+
+      - name: Build
+        run: uv build
+
+      # The report page is a data file inside the package: a wheel without it installs a CLI
+      # with nothing to open, and no test would notice.
+      - name: The wheel carries the page
+        run: unzip -l dist/*.whl | grep -q 'organella/report/organella_report.html'
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Named so the publisher on PyPI can be pinned to it, and so a release can be gated on
+    # a review in the repository's settings.
+    environment: pypi
+    permissions:
+      id-token: write        # the only thing trusted publishing needs: no token is stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v5
+
+      # `always`, so a misconfigured publisher fails loudly instead of quietly asking for a
+      # password. --check-url lets a re-run skip what is already uploaded rather than error.
+      - name: Publish
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/organella/

organella-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Editors
+.idea/
+.vscode/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+
+# What a run writes: the report, and the geometry that goes beside it
+report.parquet
+*_meshes/
+
+# What `uv build` leaves behind
+dist/

organella-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ida-mdc / Organella contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

organella-0.1.0/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.5
+Name: organella
+Version: 0.1.0
+Summary: Spatial analysis of segmented objects: measure a batch of them, and read the result in one standalone page
+Project-URL: Homepage, https://ida-mdc.github.io/organella/
+Project-URL: Repository, https://github.com/ida-mdc/organella
+Project-URL: Issues, https://github.com/ida-mdc/organella/issues
+Author: Helmholtz Imaging Engineering & Support Unit MDC
+License-Expression: MIT
+License-File: LICENSE
+Keywords: FIB-SEM,electron microscopy,image analysis,microscopy,morphometry,organelles,parquet,segmentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: crackle-codec
+Requires-Dist: edt>=2.4.0
+Requires-Dist: fast-simplification>=0.1.6
+Requires-Dist: imagecodecs
+Requires-Dist: kimimaro>=4.0.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: polars>=1.0.0
+Requires-Dist: posix-ipc
+Requires-Dist: psutil
+Requires-Dist: pyarrow
+Requires-Dist: scikit-image>=0.23.0
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: simpleitk>=2.3
+Requires-Dist: tifffile>=2024.5.0
+Provides-Extra: remote
+Requires-Dist: s3fs>=2023.6.0; extra == 'remote'
+Requires-Dist: zarr<3,>=2.16; extra == 'remote'
+Provides-Extra: test
+Requires-Dist: duckdb>=1.0; extra == 'test'
+Requires-Dist: pytest>=8.3.5; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Organella: measuring label relationships in 3D
+
+<img src="https://raw.githubusercontent.com/ida-mdc/organella/main/docs/organella.png" alt="A figure drawn entirely out of organelles, holding a measuring tape" align="right" width="190">
+
+Organella measures segmented objects - 2D or 3D, one or a batch of them - and produces a
+single report you read in one standalone page: distributions, distances, contacts, and the
+objects themselves in 3D.
+
+### [Open the viewer](https://ida-mdc.github.io/organella/)
+
+Drop a `report.parquet` on it and every chart is drawn in your browser. Nothing is uploaded
+and no server runs, so a report can be mailed to a collaborator with a link to that page.
+
+Or read one that is already up: **[seven mouse β cells, from Müller et al.](https://ida-mdc.github.io/organella/?data=https%3A%2F%2Fdcache-doma-door01.desy.de%2FHelmholtz%2FHIP%2Fcollaborations%2FOrganella%2Freports%2Fmueller-betacells.parquet)** - FIB-SEM,
+eight structures, with its geometry beside it so the 3D sections draw.
+
+An **object** is one segmented thing measured as a whole, given as a folder: a source image,
+one mask that bounds the object, and the label/mask volumes inside it. For example, object can be a cell
+bounded by its plasma membrane (`--object-mask pm`). Specifying the object bound is optional. 
+Everything inside is clipped to it by default, because a field of view often holds
+neighbouring cells. `--no-clip` measures them anyway.
+
+<br clear="right">
+
+## Screenshots from the reports
+
+|  |  |
+| --- | --- |
+| [![The 3D view of a cell drawn from its geometry](https://raw.githubusercontent.com/ida-mdc/organella/main/docs/report-3d.png)](https://raw.githubusercontent.com/ida-mdc/organella/main/docs/report-3d.png)<br>**The object in 3D,** from the geometry a `--with-mesh` run wrote. Structures switch on and off, colour by a metric, and explode pushes every instance out along its own direction from the centre. | [![Composition per object and boxes per group](https://raw.githubusercontent.com/ida-mdc/organella/main/docs/report-distributions.png)](https://raw.githubusercontent.com/ida-mdc/organella/main/docs/report-distributions.png)<br>**Composition, and groups compared.** How much of each structure there is in each object, and a box per group with Mann-Whitney brackets between whatever the charts are faceted by. |
+| [![The instance gallery, microtubules sorted by skeleton length](https://raw.githubusercontent.com/ida-mdc/organella/main/docs/report-instances.png)](https://raw.githubusercontent.com/ida-mdc/organella/main/docs/report-instances.png)<br>**The instances behind a distribution:** the highest, the lowest, or a fair sample of any metric. Click one to look at it properly. | [![Voxel-distance histograms, one panel per target structure](https://raw.githubusercontent.com/ida-mdc/organella/main/docs/report-voxel-distances.png)](https://raw.githubusercontent.com/ida-mdc/organella/main/docs/report-voxel-distances.png)<br>**Every voxel, by distance.** A structure's voxels binned by how far each one is from another structure, one panel per target. |
+
+## Workflow
+
+1. Organise your images in one of the [input layouts](#your-input).
+2. `organella dry-run` to check what will be analysed.
+3. `organella process` to write `report.parquet` and, with `--with-mesh`, the geometry.
+4. `organella view` to open the report page on it.
+5. Optionally import an object's geometry into [Blender](#blender).
+
+## Try it
+
+First, [install uv](https://docs.astral.sh/uv/getting-started/installation/) (or install the package via pip without uv, but uv is cool).
+
+Next, install Organella:
+
+```bash
+uv pip install "organella @ git+https://github.com/ida-mdc/organella.git@main"
+```
+
+Then test, measure, and view your label dataset:
+
+```bash
+organella dry-run experiment/
+organella process experiment/ -o report.parquet --with-mesh
+organella view report.parquet
+```
+
+The handful of arguments worth knowing from the start:
+
+| | |
+| --- | --- |
+| `--object-mask pm` | the mask that bounds each object. It decides the origin of every distance and polarity, and everything inside it is clipped to it, so it is never guessed - `dry-run` lists the masks each folder has |
+| `-p control -p treated` | subdirectories to import as groups. That grouping becomes the default comparison in every chart |
+| `--voxel-size-um 0.1,0.02,0.02` | needed when the images carry no calibration, since a size is never invented. `y,x` for a plane |
+| `--skeletons mito,ER` | branches, length and tortuosity for the structures worth it. Opt-in: it is the most expensive thing in a run |
+| `--entities mito,ER` | measure only these. Each entity is another full-size channel, so a subject carrying 117 structures needs this to fit in memory |
+| `--with-mesh` | also write the geometry the 3D sections and Blender read, to `<output>_meshes/` |
+
+Every argument is listed under [Parameters of `process`](#parameters-of-process).
+
+**Check the input first.** `dry-run` reads image headers only - no analysis, no output - 
+and prints per object the source image, the label and mask entities
+found (`*` marks the object mask), and anything that looks wrong. Then which entities are
+missing in which objects, and a suggested `--max-workers`. Exit code is `1` if any object
+cannot be analysed.
+
+```text
+control/cell_b
+  source  sample_b.tif   [12.4 MB stacked]
+  labels  mito
+  masks   nucleus, pm*
+  warn    ignored readme_overlay.tif: not <prefix>_<name>_label|labels|mask
+
+===== 3 object folder(s) =====  (* = object mask)
+  label:mito               2/3   ← missing in some objects
+  mask:pm                  3/3
+```
+
+## Reading the report
+
+`organella view report.parquet` serves the report, its geometry and the page from one
+localhost origin and opens it. Or open **<https://ida-mdc.github.io/organella/>** and drop
+`report.parquet` on it: the page parses the parquet in the browser, so nothing is uploaded and
+no server runs.
+
+**The 3D sections need the geometry too**. Press **Add geometry** and pick either the `report_meshes` folder or the
+`geometry.parquet` files themselves; The `organelle view` command attaches them for you and you don't need to do anything else.
+
+In the page, **Charts** switches every panel between boxes and histograms, and
+**Significance** puts Mann-Whitney brackets between whatever the charts are faceted by. Every
+column carries its own description in the report, so the page explains each metric under the
+chart of it.
+
+## Your input
+
+Entity files must match `<prefix>_<name>_label.tif` (or `_labels.tif`) and
+`<prefix>_<name>_mask.tif`, where `<prefix>` is the source image basename. The prefix is taken
+off the front, so the entity name is whatever is left and may have underscores in it:
+`s0011_rib_left_11_mask.tif` is the entity `rib_left_11`.
+
+```text
+my_cell/
+  sample.tif
+  sample_mito_label.tif
+  sample_nucleus_mask.tif
+  sample_membrane_mask.tif
+```
+
+An object folder can sit on its own, in a flat batch (`cells/cell_a/`, `cells/cell_b/`), or in
+a grouped batch (`experiment/control/cell_a/`, `experiment/treated/cell_b/`), where the group
+folder is what `-p` imports.
+
+**Other formats.** NIfTI (`.nii`, `.nii.gz`), NRRD and MetaImage are read through SimpleITK.
+Their headers carry a reliable voxel size, which TIFF often does not; spacing is read as
+millimetres, the convention every reader of these files uses.
+ 
+**Entities in a subfolder** named by nothing but the structure - a `segmentations/`, `masks/`
+or `labels/` folder beside the source image. There is no prefix to strip, and label-or-mask
+is read off the content rather than guessed from the name.
+ 
+**A remote store, read as a crop.** A folder holding one `source.json` and no images names a
+chunked store (N5 or Zarr, local or on S3), the arrays in it, and the window to read. A 512³
+crop of OpenOrganelle's 122-gigavoxel HeLa cell is 0.64% of it, in under five seconds, at
+full 4 nm resolution. Needs the `remote` extra: `pip install 'organella[remote]'`.
+
+```json
+{
+  "store": "s3://janelia-cosem-datasets/jrc_hela-2/jrc_hela-2.n5",
+  "scale": "s0",
+  "crop": "3712:4224,256:768,5760:6272",
+  "source": "em/fibsem-uint16",
+  "entities": { "mito": "labels/mito_seg", "er": "labels/er_seg" }
+}
+```
+
+## Output
+
+```text
+report.parquet                            # rows per object, structure, instance and contact
+report_meshes/<object>/geometry.parquet   # only with --with-mesh
+```
+
+Everything measured lands in `report.parquet`, as rows at four depths told apart by `row_type`:
+
+| `row_type` | `obs_level` | one row per |
+| --- | --- | --- |
+| `object` | 0 | object folder: extent, provenance, and the whole-object totals |
+| `entity` | 1 | structure, by name: volume, surface area, sphericity, instance counts |
+| `instance` | 2 | labelled instance: its own size, shape, polarity and nearest neighbour |
+| `distance` | 2 | instance × target structure: how far that instance is from it |
+| `contact` | 2 | touching pair of instances of one structure, with their gap |
+
+Geometry goes beside the report rather than in it, because meshes would multiply the size of a
+table every query loads. One `geometry.parquet` per object holds a surface per instance (an
+outline, for a 2D object), the skeletons, and the touching pairs, so it stands on its own for
+Blender and for a hosted copy. The object row records where, in `mesh_geometry_file`.
+
+## Commands
+
+| | |
+| --- | --- |
+| `organella dry-run DIR` | what would be analysed, from headers only |
+| `organella process DIR -o REPORT` | measure a batch, write the report |
+| `organella mesh DIR -o OUTDIR` | geometry only, for a report you already have |
+| `organella view REPORT` | serve the report, its geometry and the page, and open it |
+| `organella page` | print the path of the standalone page |
+| `organella colours REPORT PALETTE` | recolour a report in about a second |
+| `organella describe REPORT TEXT` | say what the data is: credits, a citation, a licence. `-` reads it from standard input |
+
+`dry-run` takes `--object-mask NAME`, to check every folder has it rather than only listing
+what they have. `view` takes `--port` (default 8052) and `--no-browser`. `mesh` takes
+`-o, --out-dir` for where to write `<object>/geometry.parquet`, plus the input, geometry and
+run parameters below and `--no-contacts`.
+
+## Parameters of `process`
+
+**Input**
+
+| | |
+| --- | --- |
+| `-o, --output FILE` | where to write the report. Required |
+| `-p, --paths TEXT` | subdirectory to import as its own group, repeatable. Becomes the default grouping in every chart |
+| `--object-mask NAME` | the mask that bounds each object. Never guessed: it decides the origin of every distance and polarity. Left out, entities are measured where they lie |
+| `--description TEXT` | what this data is and who it credits. It travels in the report, and the page shows it above the first section, so a report you send arrives with its provenance |
+| `--object-noun WORD` | what one measured thing is called in the report, e.g. `cell`, or `nucleus/nuclei` for an irregular plural. Presentation only |
+| `--voxel-size-um Z,Y,X` | voxel size in µm; `y,x` for a plane. Inferred from the source metadata when omitted, and refused rather than invented if there is none |
+| `--entities NAMES` | measure only these, plus the object mask. Each entity is another full-size channel, so a 117-structure subject needs selecting down before it fits in memory |
+| `--label-map FILE` | JSON of `{"1": "liver"}`, splitting one volume whose ids each mean a different structure into an entity per id. Only named ids become entities |
+| `--label-map-entity NAME` | which entity `--label-map` splits. Needed only when a folder has more than one label entity, where leaving it out is an error rather than a guess |
+| `--auto-label-masks` | promote masks with several connected components to label entities |
+
+**What gets measured**
+
+| | |
+| --- | --- |
+| `--no-clip` | measure outside the object mask too. Clipped to it by default, since that is what naming a bounding mask means |
+| `--no-instances` | entity-level morphology only: no per-instance rows |
+| `--no-contacts` | skip the contact rows |
+| `--contact-max-um T` | largest gap between two instances of one structure that still counts as a contact. Default 0.5 |
+| `--skeletons NAMES` | structures to skeletonise, for branches, length and tortuosity. Opt-in: it is the most expensive thing in a run, and a granule's skeleton is one branch the length of its diameter |
+| `--max-skeleton-voxels N` | skip skeletons for instances above this voxel count. Default 500000 |
+| `--polarity-spread` | also measure each instance's angular spread on the polarity sphere |
+| `--distance-histograms` | also measure per-instance distance distributions, not just the minimum |
+| `--colours FILE` | also `--colors`. JSON of `{"mito": "#d62728"}`. Lands in the report, so every chart draws that structure the same. Unnamed structures keep the built-in palette |
+
+**Geometry**, all of it only with `--with-mesh`
+
+| | |
+| --- | --- |
+| `--with-mesh` | also write per-object geometry for the 3D views and Blender. Goes to `<output>_meshes/`, never into the parquet |
+| `--geometry-as NAME=KIND,...` | how a structure's surface is stored: `mesh`, `ellipsoid` or `tube`, e.g. `vesicle=ellipsoid`. Decided from the measured shape when unnamed - a round instance becomes a 60-byte ellipsoid, which is what makes tens of thousands drawable. No measurement changes; the surface is only ever drawn |
+| `--mesh-max-vertices N` | most vertices one surface keeps; 0 lifts the cap. Default 200000. A decimation *fraction* bounds nothing: at 0.5 one ER sheet was still 2.87 million vertices and 86 MB |
+| `--mesh-smooth-sigma SIGMA` | Gaussian sigma before marching cubes. Default 0.7; 0 disables |
+| `--mesh-step-size N` | marching-cubes step size; 1 is full resolution. Default 2 |
+| `--mesh-target-reduction F` | decimation fraction. Default 0.8, keeping ~20% of faces |
+| `--mesh-level L` | iso-surface level on the signed distance field. Default 0 |
+| `--mesh-surface-method` | `marching-cubes` or `surface-nets`. The dual method has ~30% less staircase noise, no fewer vertices, and is 66% slower |
+| `--mesh-workers N` | processes meshing one object's instances. Default: the cores the object pool is not using |
+| `--reuse-geometry` | keep any `geometry.parquet` an object already has. Meshing dominates a run, so a batch that died partway finishes in minutes |
+
+**The run**
+
+| | |
+| --- | --- |
+| `--max-workers N` | worker processes. Default: worked out from memory, since one object can need gigabytes |
+| `--num-threads N` | kimimaro worker count. Default 1, because objects already run in parallel |
+| `--resume` | skip objects an interrupted run already measured. Each object's rows go to `<output>_parts/` as it finishes and are removed once the report is written |
+
+## Sharing a report
+
+The geometry stays a folder of one file per object, so it travels with
+the report in one of two shapes:
+
+- hand over `report.parquet` and its `report_meshes/` folder, and the reader runs
+  `organella view report.parquet`
+- or upload the two together, unchanged, and open the page with `?data=<url of the parquet>`.
+  The geometry is looked for beside the parquet as `<name>_meshes/`, so there is nothing else
+  to pass. If the files sit on a different origin than the page, that server has to allow
+  cross-origin requests - GitHub Pages does, a bare `python -m http.server` does not.
+
+
+## Development
+
+```bash
+uv venv --python 3.12 .venv
+source .venv/bin/activate
+uv pip install -e '.[test]'      # the suite needs pytest and duckdb
+.venv/bin/python -m pytest
+```
+
+The report page is one file with no build step, edit
+[`src/organella/report/organella_report.html`](src/organella/report/organella_report.html)
+and reload the browser. The test suite runs it through
+node - how a report is read into it, the maths its panels draw, the queries its 3D
+sections build, and every section drawn against a stub DOM:
+
+```bash
+.venv/bin/python -m pytest tests/test_report_page.py
+```
+
+That harness never runs the real load path - DuckDB-WASM, the parquet read, WebGL - so a
+change to how the page opens a report has to be checked in a browser.
+
+## Blender
+
+`geometry_to_blender.py` imports an object's `geometry.parquet`. It needs Blender with `pandas`
+and `pyarrow` in Blender's own Python
+(`<blender>/python/bin/python3 -m pip install pandas pyarrow`), and geometry from a **3D**
+object - a 2D object carries outlines, which the report's gallery draws and Blender has no use
+for.
+
+```bash
+blender --background --python geometry_to_blender.py -- geometry.parquet [out.blend] [out.png]
+```
+
+Or open the script in Blender's Script Editor, set `GEOMETRY_PATH` (optionally `OUT_BLEND`,
+`OUT_RENDER`) and run it with `Alt+P`.