matter-vis 0.0.0__tar.gz

matter_vis-0.0.0/.github/workflows/release.yml

@@ -0,0 +1,151 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  release-checks:
+    name: Release metadata checks
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      tag: ${{ steps.release.outputs.tag }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate release tag
+        id: release
+        shell: bash
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME}"
+          if [[ ! "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Release tag must match vX.Y.Z: ${TAG}" >&2
+            exit 1
+          fi
+
+          echo "tag=${TAG}" >> "${GITHUB_OUTPUT}"
+          echo "version=${TAG#v}" >> "${GITHUB_OUTPUT}"
+
+  tests:
+    name: Unit tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: release-checks
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+
+      - name: Run tests
+        run: pytest tests/
+
+  build-package:
+    name: Build package distributions
+    runs-on: ubuntu-latest
+    needs: [release-checks, tests]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: pip
+
+      - name: Build source and wheel distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Verify built version
+        env:
+          EXPECTED_VERSION: ${{ needs.release-checks.outputs.version }}
+        run: |
+          python -m pip install --no-deps dist/*.whl
+          python - <<'PY'
+          import importlib.metadata
+          import os
+
+          actual = importlib.metadata.version("matter-vis")
+          expected = os.environ["EXPECTED_VERSION"]
+          if actual != expected:
+              raise SystemExit(f"Built version {actual!r} does not match tag version {expected!r}")
+          print(f"matter-vis {actual}")
+          PY
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [release-checks, build-package]
+    environment:
+      name: pypi
+      url: https://pypi.org/project/matter-vis/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  create-github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [release-checks, publish-pypi]
+    permissions:
+      contents: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" dist/* \
+            --generate-notes \
+            --title "${GITHUB_REF_NAME}"

matter_vis-0.0.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+
+.local/
+.exports/
+catalog.local.json
+
+uploads/
+exports/
+scripts/_outputs/
+scripts/data/HPEP.cif
+scripts/data/MPEP.cif
+scripts/data/PEP.cif
+scripts/data/SY.cif
+scripts/_data/
+
+.DS_Store
+Thumbs.db
+
+scripts/private/
+verification_screens/
+_tmp/
+server.log

matter_vis-0.0.0/AGENTS.md

@@ -0,0 +1,104 @@
+# MatterVis — Developer Contract
+
+This file is for agents and humans **modifying** MatterVis. It is the
+top-level contract only; module/API details belong in linked docs.
+Keep this file short, architectural, and free of function-specific rules.
+
+## Read the right document first
+
+- Caller-facing API contracts: [`agents/README.md`](agents/README.md).
+- Detailed feature contracts: `agents/*_api.md` and
+  [`agents/dash_service.md`](agents/dash_service.md).
+- Implementation notes and historical traps:
+  [`docs/dev-notes.md`](docs/dev-notes.md),
+  [`docs/postmortems.md`](docs/postmortems.md).
+
+If a change touches a public feature, read the matching `agents/` file
+before editing. If a change touches chemistry delegation, disorder,
+fragmentation, topology, slabs, or loader/render boundaries, also read
+`docs/dev-notes.md`.
+
+## Repository ownership
+
+| Path | Owns |
+| --- | --- |
+| `crystal_viewer/` | Python library: structure, operations, analysis, render, scene, math, utilities |
+| `api/` | REST/WebSocket service surface for scripts and agents |
+| `app/` | Dash Python BFF, callbacks, layouts, `ViewerBackend` |
+| `frontend/` | Browser-only JavaScript/CSS assets loaded by Dash |
+| `agents/` | Public caller contracts and automation-facing API docs |
+| `docs/` | Human docs, developer notes, postmortems, score tables |
+| `scripts/` | Runnable examples and regression figure generators |
+| `tests/` | Unit and integration tests |
+
+New features should normally fit one of these owners. Avoid new
+top-level modules unless the existing ownership model cannot stretch.
+
+## Non-negotiable design principles
+
+1. **Separate caller style from library capability.** No journal,
+   project, or paper-specific naming under `crystal_viewer/`. Defaults
+   are conveniences; styling must be caller-overridable.
+2. **Keep APIs layered.** Prefer pure primitives at the bottom,
+   composable builders above them, and convenience wrappers at the top.
+   Callers must be able to drop down a layer without reimplementing math.
+3. **Do not mutate shared module state.** Exposed palettes/configs are
+   readable defaults. Overrides must flow through explicit call/state data.
+4. **Reuse before reinventing.** Before adding geometry, chemistry,
+   topology, PBC, shape, disorder, or slab logic, check upstream
+   `molcrys_kit` and existing MatterVis modules for the current primitive.
+5. **Respect ownership boundaries.** Browser code stays in `frontend/`,
+   service code in `api/` or `app/`, reusable library code in
+   `crystal_viewer/`, and chemistry semantics in `molcrys_kit`.
+6. **Keep operation paths distinct.** Source operations work on real
+   crystal objects and return through the loader. Display operations work
+   on manifested scene data and must not pretend to create source objects.
+7. **Keep math domain-neutral.** Projection, rotation, ellipsoid, and PBC
+   primitives may live in math; coordination, labels, covalent radii,
+   fragments, and species semantics do not.
+8. **Separate state, assembly, and snapshots.** Editable scene state,
+   render assembly, manual overlays, and scene-to-source snapshots have
+   different owners; do not blur them for convenience.
+9. **Keep interactive work asynchronous.** Dash/Flask request callbacks
+   must not run expensive topology or figure assembly inline. Use the
+   established worker/intent/state flow.
+10. **Visually verify rendering changes.** Static export can fail
+    silently; regenerate the relevant script output and inspect it.
+
+## MolCrysKit boundary
+
+`molcrys_kit` owns chemistry: molecule grouping, PBC unwrapping,
+packing shells, shape classification, disorder resolution, slabs, and
+related provenance. MatterVis owns loading adapters, scene state,
+rendering, UI, and service surfaces.
+
+When upstream already computes a chemistry quantity, consume it as the
+single source of truth. Do not re-derive it locally “for safety”. When
+upstream deprecates a primitive, read the replacement docs and update
+the public contract in `agents/` if the payload changes.
+
+## Public contracts
+
+The caller-visible guarantees for cube rendering, compass overlays,
+scene figures, ORTEP, atom/bond groups, transforms, polyhedra,
+selection, config, REST, and WebSocket behavior live under `agents/`.
+Breaking one of those contracts requires updating the matching doc;
+back-incompatible changes require an API/version bump.
+
+## Tests, lint, and examples
+
+- Unit tests: `pytest tests/`.
+- Lint: `ruff check crystal_viewer/`.
+- Example regressions: run the relevant `python scripts/<n>_*.py` and
+  inspect the generated artifact under `scripts/_outputs/`.
+
+## Adding or changing code
+
+- Name modules and symbols for the data/operation, not a journal,
+  project, or one-off output.
+- Add new capability at the lowest layer that fits, then wrap upward.
+- Expose style choices as kwargs/state fields instead of constants.
+- Update the matching `agents/` file for public API changes.
+- Update examples and tests when behavior changes.
+- Put deep implementation warnings in `docs/dev-notes.md` or local
+  code comments, not in this top-level contract.

matter_vis-0.0.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: matter-vis
+Version: 0.0.0
+Summary: Publication-quality crystal structure visualization + terminal viewer
+Requires-Python: >=3.10
+Requires-Dist: dash
+Requires-Dist: plotly
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-image
+Requires-Dist: gemmi
+Requires-Dist: pymatgen
+Requires-Dist: kaleido
+Requires-Dist: flask-sock
+Requires-Dist: flask-compress
+Requires-Dist: matplotlib
+Requires-Dist: pillow
+Requires-Dist: ase
+Requires-Dist: networkx
+Requires-Dist: textual
+Requires-Dist: molcrys-kit>=0.6.1
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: dev
+Requires-Dist: matter-vis[test]; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: ruff; extra == "dev"

matter_vis-0.0.0/README.md

@@ -0,0 +1,366 @@
+# MatterVis · crystal_viewer
+
+Standalone Dash / Plotly frontend and automation toolkit for molecular
+perchlorate crystals (**A**₂**B**(ClO₄)₄ and friends). CIF in — interactive 3D
+viewer, coordination-topology scores, publication-quality Matplotlib export
+and a REST + WebSocket API for other agents, all out.
+
+![banner](docs/images/banner.png)
+
+Everything in this README is reproduced from the bundled
+`scripts/data/DAP-4.cif` (a triclinic diammonium diperchlorate `P1` cell,
+see [`scripts/data/README.md`](scripts/data/README.md)); swap it for your
+own CIF with a single flag.
+
+---
+
+## Highlights
+
+- **Browser viewer** — Dash front-end, drag-and-drop CIF upload, formula /
+  unit-cell / asymmetric-unit / isolated-cluster display, `Mesh3d` atoms and
+  bonds with a fast `Scatter3d` fallback for large cells.
+- **Coordination topology** — automatic CN detection via the nearest-neighbour
+  gap, angular RMSD vs 12 ideal polyhedra (CN 8-12), planarity RMS of any
+  5-atom subset and a prism / antiprism twist check. See
+  [`docs/scores.md`](docs/scores.md).
+- **Publication export** — vendored ORTEP-style Matplotlib renderer with
+  correct depth ordering, two-colour bonds, smart label placement and
+  configurable presets. Plotly path shares radius-aware viewport bounds so
+  large halides never clip at the panel edge.
+- **Multi-panel figures** — `uniform_viewport(scenes)` stamps a shared
+  world-cube on any list of scenes so every `build_figure` call emits at the
+  same physical length per pixel. Drop-in for N-up comparison figures.
+- **Automation** — REST + WebSocket API on the same Flask server. Drive the
+  viewer from notebooks, agents or subprocesses (`GET /api/v1/state`,
+  `POST /api/v1/topology`, `GET /api/v1/screenshot`, ...).
+- **Zero catalog required** — the package ships with a single public CIF so
+  `mat-vis serve --cif scripts/data/DAP-4.cif` just works.
+
+## Install
+
+```bash
+git clone https://github.com/SchrodingersCattt/MatterVis.git
+cd MatterVis
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+`molcrys_kit` is optional. When available the per-fragment **A / B / X**
+heuristic falls back to its classifier; otherwise `crystal_viewer` uses its
+built-in element / size heuristics. The browser UI doesn't expose A/B/X
+labels directly -- it lists the stoichiometric formulas it detects (e.g.
+`C6N2 ×2`, `ClO4 ×4`, `N ×1`) so the same controls work for non-perovskite
+crystals.
+
+## Quick render (CLI)
+
+Generate publication-quality figures from CIF files without launching the
+browser:
+
+```bash
+# PNG with default ball-and-stick style
+mat-vis render structure.cif -o figure.png
+
+# PDF, full unit cell, ORTEP hatch shading in greyscale
+mat-vis render structure.cif -o figure.pdf \
+  --view unit_cell --style ortep --ortep-mode ortep_hatch --monochrome
+
+# Interactive HTML for supplementary information
+mat-vis render structure.cif -o si_figure.html \
+  --show-hydrogen --show-labels
+```
+
+See [`docs/cli.md`](docs/cli.md) for the full flag reference, common
+recipes, and advanced `--config` JSON usage.
+
+## Launch the browser viewer
+
+```bash
+mat-vis serve --cif scripts/data/DAP-4.cif
+# Serving crystal viewer at http://0.0.0.0:50001
+```
+
+Additional flags:
+
+```bash
+mat-vis serve --port 8051            # pick a port
+mat-vis serve --host 127.0.0.1       # bind to localhost only
+mat-vis serve --structure DAP-4      # limit catalog to one name
+mat-vis serve --cif a.cif --cif b.cif --cif c.cif
+```
+
+`--cif` is `action="append"` -- repeat the flag once per CIF file you want to
+preload. The viewer listens on `127.0.0.1` by default; pass `--host 0.0.0.0`
+when the dev box is behind a port-forwarding proxy (see below).
+
+### Remote dev boxes (Bohrium and friends)
+
+Container platforms typically only expose a small range of ports. On a
+**Bohrium tech development machine** the public proxy maps the URL
+`http://<your-id>.bohrium.tech:5000X` straight through to container port
+`5000X` for `X` in `1..5` -- nothing else is reachable from outside. Two
+common gotchas:
+
+1. **Bind to `0.0.0.0`.** Loopback-only listeners (the `--host 127.0.0.1`
+   default) never see traffic from the platform proxy.
+2. **Use one of `50001`-`50005`.** Other ports on the container may be in
+   use by Jupyter / MCP servers; check with `ss -ltn | grep 5000` before
+   you pick one.
+
+Putting it together for a Bohrium dev box:
+
+```bash
+mat-vis serve --host 0.0.0.0 --port 50001 \
+  --cif scripts/data/DAP-4.cif --cif scripts/data/SY.cif
+# Reachable at http://<your-id>.bohrium.tech:50001/
+```
+
+If the URL still ERR_CONNECTION_REFUSED, port `50001` is already taken on
+that container -- pick another from the `50001-50005` window.
+
+### Open the page in a real browser, not an embedded webview
+
+Cursor's *Simple Browser*, VS Code's *preview panel* and similar
+Electron-hosted webviews dispatch click events at the DOM level but
+do not always propagate them through React 16's synthetic event
+system that Dash binds onto. The visible failure mode is brutal:
+**every checkbox / dropdown / slider appears to "click" but nothing
+happens** -- the figure never updates, the network tab is silent
+(no `/_dash-update-component` POST is ever sent), and the user
+concludes the app is broken.
+
+The viewer auto-detects this case by sniffing the
+`User-Agent` and renders a sticky red banner at the top of the page
+with a one-click *Copy URL* button. Paste the URL into Chrome, Edge,
+Firefox or Safari and every control will start firing as expected.
+
+A built-in wire-tap strip is also available behind the
+`?diag=1` query parameter -- it shows live counts of clicks, Dash
+POSTs and JS errors so you can tell at a glance whether a "no
+response" report is a DOM problem (no clicks), an event-delegation
+problem (clicks but no POST), or a server problem (POST but no OK).
+
+For server-side debugging the same information is available via
+`MATTERVIS_AUDIT=1 mat-vis serve ...`, which prints a
+one-line summary of every non-poll callback (changedPropIds,
+duration, payload size, originating IP / User-Agent).
+
+See [`AGENTS.md`](AGENTS.md) for every REST / WebSocket endpoint and the full
+set of stable UI element IDs.
+
+## Headless scripts
+
+Every script in [`scripts/`](scripts) can be run end-to-end without a
+browser:
+
+```bash
+python scripts/01_quick_render.py           # CIF -> PNG + interactive HTML
+python scripts/02_coordination_analysis.py  # coordination shell + all scores
+python scripts/03_display_modes_panel.py    # formula / unit cell / shell
+python scripts/04_static_publication.py     # ORTEP-style PNG + PDF
+python scripts/05_app_and_api.py            # launch app + drive it via REST
+python scripts/06_cp2k_cube_orbital.py --cube orbital.cube  # CP2K/Gaussian cube isosurfaces
+```
+
+Outputs land under `scripts/_outputs/` (gitignored). Regenerate the README
+showcase images with `python docs/build_images.py`.
+
+### CP2K / Gaussian cube orbitals
+
+MatterVis can render CP2K or Gaussian `.cube` orbital files as paired positive
+and negative Plotly isosurfaces, with atom positions overlaid from the cube
+header:
+
+```bash
+python scripts/06_cp2k_cube_orbital.py \
+  --cube /path/to/cp2k-WFN_00292_1-1_0.cube \
+  --output-prefix HOCO \
+  --stride 2 \
+  --percentile 98.5
+```
+
+The reader converts cube coordinates from Bohr to Å and automatically chooses a
+robust isovalue from the absolute-value distribution unless `--isovalue` is
+provided. HTML output is always generated; PNG export is attempted when Kaleido
+is available.
+
+### 1. `01_quick_render.py` — CIF to unit cell in ten lines
+
+```python
+from crystal_viewer.loader import build_bundle_scene, build_loaded_crystal
+from crystal_viewer.renderer import build_figure
+from crystal_viewer.scene import scene_style
+
+bundle = build_loaded_crystal(name="DAP-4", cif_path="scripts/data/DAP-4.cif")
+scene  = build_bundle_scene(bundle, display_mode="unit_cell")
+style  = scene_style(scene, {"show_unit_cell": True})
+
+fig = build_figure(scene, style)
+fig.write_image("dap4.png", width=900, height=720, scale=2)
+fig.write_html("dap4.html", include_plotlyjs="cdn")
+```
+
+![unit cell](docs/images/feature_unit_cell.png)
+
+### 2. `02_coordination_analysis.py` — topology scores with one function call
+
+```python
+from crystal_viewer.loader import build_loaded_crystal
+from crystal_viewer.topology import analyze_topology
+
+bundle = build_loaded_crystal(name="DAP-4", cif_path="scripts/data/DAP-4.cif")
+# Pick the first DABCO ring -- in DAP-4 those have stoichiometry C6N2.
+target = next(f for f in bundle.topology_fragment_table if f.get("formula") == "C6N2")
+result = analyze_topology(bundle, center_index=target["index"], cutoff=8.0)
+
+print(result["coordination_number"])             # 9
+print(result["shape"]["primary_label"])          # tricapped_trigonal_prism
+print(result["shape"]["label_modifier"])         # distorted
+print(result["gap_info"]["gap_value"])           # 0.124 Å
+```
+
+The example also dumps a tidy `02_coordination_summary.json` with every score
+broken out — see [`docs/scores.md`](docs/scores.md) for a full reference.
+
+<p>
+  <img src="docs/images/feature_coordination.png" alt="coordination hull" width="49%"/>
+  <img src="docs/images/feature_histogram.png"    alt="distance histogram" width="49%"/>
+</p>
+
+### 3. `03_display_modes_panel.py` — side-by-side display modes
+
+A single Plotly figure stitches formula unit, unit cell, and coordination
+shell together so reviewers can switch between them without reloading:
+
+![three modes](docs/images/feature_three_modes.png)
+
+### 4. `04_static_publication.py` — ORTEP-style Matplotlib export
+
+Runs the vendored `crystal_viewer.static_publication.plot_crystal` renderer (same code
+used by `POST /api/v1/export`) to produce high-DPI PNG + PDF suitable for
+Nature-style figures:
+
+![publication](docs/images/feature_publication.png)
+
+### 5. `05_app_and_api.py` — drive the live viewer over HTTP
+
+Starts `create_app()` in the background, preloads `DAP-4`, then hits
+`POST /api/v1/topology` and `GET /api/v1/screenshot`. The call sequence is a
+one-page recipe for wiring the viewer into a larger agent pipeline.
+
+## Topology scores
+
+`analyze_topology()` (and the REST `POST /api/v1/topology`) return five
+named scores that together describe a coordination shell. One line summary:
+
+| Score | Module field | What it measures |
+| --- | --- | --- |
+| Coordination number | `coordination_number` + `gap_info.gap_value` | Neighbours in the first shell, picked by the largest distance jump. |
+| Shape classification | `shape.primary_label` / `label_modifier` / `cshm_value` | CShM-based polyhedron name + distortion tier (`clean` / `distorted` / `ambiguous`) for CN 4-12. |
+| Planarity RMS | `planarity.best_rms` / `best_indices` | Best-fit plane through any 5 shell atoms (Å). |
+| Prism / antiprism twist | `prism_analysis.twist_deg` / `classification` | Average inter-ring rotation; threshold 18°, only for CN ≥ 10. |
+| Convex hull | `hull.vertices` / `simplices` / `edges` | Geometry the viewer draws as the purple polyhedron. |
+
+See [`docs/scores.md`](docs/scores.md) for how each score is computed,
+reasonable thresholds, and worked numbers for DAP-4.
+
+## Rendering isolated clusters
+
+Perchlorate-cluster CIFs (dummy 100 Å cell, atoms listed in P1, no periodic
+imaging expected) go through a dedicated display mode that skips formula-unit
+trimming and MIC bond search:
+
+```python
+from crystal_viewer.scene import build_scene_from_cif
+from crystal_viewer.renderer import build_figure, uniform_viewport
+from crystal_viewer.presets import DEFAULT_STYLE, deep_merge
+
+# Palette override: add elements not in the vendored table (I, Na, K, Rb, …)
+# or restyle existing ones for a specific figure.
+style = deep_merge(DEFAULT_STYLE, {
+    "show_title": False,
+    "show_labels": False,
+    "show_axes": False,
+    "show_hydrogen": True,
+    "atom_scale": 0.9,
+    "bond_radius": 0.14,
+    "element_colors": {"I": "#940094", "Na": "#E6D11E", "K": "#AB82FF"},
+})
+preset = {"version": 1, "style": style, "structures": {}}
+
+scenes = [
+    build_scene_from_cif(
+        name=name,
+        cif_path=f"clusters/{name}.cif",
+        title=name,
+        preset=preset,
+        show_hydrogen=True,
+        display_mode="cluster",
+    )
+    for name in ("DAI-1", "DAI-4", "DAP-2", "DAP-M4")
+]
+
+# Pin every panel to the same world cube so panel-to-panel scale is identical
+# and no Cl / I atoms clip at the edge. The cube side = biggest scene span +
+# padding (in Å).
+uniform_viewport(scenes, padding=0.5)
+
+for scene in scenes:
+    fig = build_figure(scene, style)
+    fig.write_image(f"{scene['name']}.png", width=600, height=600, scale=2)
+```
+
+Every scene now renders at the same Å-per-pixel, with radius-aware bounds so
+even Cl / I / Br spheres are fully visible. `display_mode="cluster"` honours
+the stored Cartesian coordinates exactly — useful when the CIF encodes a
+hand-curated fragment rather than a crystallographic asymmetric unit.
+
+## Package layout
+
+```
+crystal_viewer/
+├── __init__.py          # re-exports create_app
+├── __main__.py          # compatibility entry point; use `mat-vis`
+├── app/                 # Dash layout, callbacks, ViewerBackend internals
+├── api/                 # REST + WebSocket blueprints
+├── render/              # Plotly viewport / traces / cache internals
+├── structure/           # CIF parsing, bonds, formula units, MolCrysKit bridge
+├── loader/              # CIF/fragment bundle loading facade + upload helpers
+├── scene/               # cell/cluster scene builder facade
+├── transforms/          # repeat/grow/slab transform primitives and pipeline
+├── topology/            # coordination-shell extraction & shape analysis
+├── style/               # atom/bond rules, palette, disorder render helpers
+├── cube/                # cube/orbital I/O, meshes, traces, export facade
+├── ortep/               # thermal ellipsoid math, billboards, traces
+├── compass/             # camera-projected lattice direction annotations
+├── renderer/            # public Plotly facade for atoms, bonds, hulls, axes
+├── presets/             # preset / style / catalog IO
+├── scenes/              # tab/session scene state
+├── perf_log/            # lightweight server event log facade
+├── depth_sort/          # matplotlib depth-order helpers
+├── viewer_backend/      # public ViewerBackend compatibility facade
+├── assets/              # Dash CSS + JS for the panel layout
+└── static_publication/  # matplotlib publication exporter
+scripts/                # runnable demo scripts (see section above)
+docs/                    # README showcase images + scores.md
+```
+
+## Notes
+
+- Plotly screenshot export uses `kaleido`; the first call is slow because
+  it spins up a headless Chromium.
+- Static publication export writes to `.exports/` (gitignored).
+- Local presets default to `.local/crystal_view_preset.json`.
+- Local catalog overrides can be supplied via `catalog.local.json` or
+  `.local/catalog.local.json`.
+- The CIF parser handles Materials-Studio style loops that omit
+  `_atom_site_disorder_*` columns — no manual cleanup required.
+- For automation details (every endpoint, stable UI IDs, WebSocket schema),
+  see [`AGENTS.md`](AGENTS.md).
+
+## Citing
+
+If you use the bundled example structure, please also credit the originating
+publication that released it — see [`scripts/data/README.md`](scripts/data/README.md).
+The `crystal_viewer` code itself is released under the repository's root
+license file.