pretty-lattice 0.1.0__tar.gz

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

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Run ruff
+        run: uv run --python ${{ matrix.python-version }} ruff check .
+
+      - name: Run pytest
+        run: uv run --python ${{ matrix.python-version }} pytest
+
+  web:
+    name: Web
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.13
+
+      - name: Install dependencies
+        working-directory: web
+        run: bun install --frozen-lockfile
+
+      - name: Run tests
+        working-directory: web
+        run: bun run test
+
+      - name: Run typecheck
+        working-directory: web
+        run: bun run typecheck
+
+      - name: Build
+        working-directory: web
+        run: bun run build

pretty_lattice-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+.DS_Store
+.codex/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyre/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.python-version
+
+# Node / Bun / frontend
+node_modules/
+dist/
+build/
+web/dist/
+.vite/
+.next/
+coverage/
+bun.lockb
+*.tsbuildinfo
+
+# Local QA artifacts
+.playwright-cli/
+output/playwright/
+tmp/
+tmp/visual-renders/
+
+# Local configuration
+.env
+.env.*
+!.env.example
+
+# Editor and OS noise
+.idea/
+.vscode/
+*.swp
+*.swo

pretty_lattice-0.1.0/AGENTS.md

@@ -0,0 +1,7 @@
+Project context managed under `docs/`. Navigate by `docs/index.md`.
+
+Use `uv` for python and `bun` for web. See `docs/development.md`.
+
+Do not use browser or Playwright testing unless explicitly asked.
+
+Use conventional commits style, such as `feat: ...` or `fix: ...`.

pretty_lattice-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Feitong Song
+
+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.

pretty_lattice-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: pretty-lattice
+Version: 0.1.0
+Summary: Local web GUI for rendering crystal structures as publication-ready figures.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pymatgen-core>=2026.5.18
+Requires-Dist: typer>=0.16.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Description-Content-Type: text/markdown
+
+<h1 align="center"><img src="web/public/favicon.svg" alt="Pretty Lattice logo" width="30" height="30"> Pretty Lattice</h1>
+
+<p align="center">
+  Pretty Lattice is a crystal visualization tool for creating beautiful, publication-ready figures.
+</p>
+
+<p align="center">
+  <a href="https://github.com/songfeitong/pretty-lattice/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/songfeitong/pretty-lattice/ci.yml?branch=main&label=build&style=flat-square"></a>
+  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12+-3776ab?style=flat-square">
+  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green?style=flat-square">
+</p>
+
+- **Pretty**: tasteful defaults for colors, materials, lighting, and depth
+- **Simple**: an intuitive browser GUI for loading, viewing, and exporting structures
+- **Reliable**: structure parsing and analysis powered by the mature [pymatgen](https://github.com/materialsproject/pymatgen) package
+- **Scalable**: smooth interaction with systems up to 10k atoms
+- **Customizable**: tune colors, radii, materials, opacity, orientation, and export settings
+
+<p align="center">
+  <img src="assets/demo.png" alt="Pretty Lattice interface preview" width="90%">
+</p>
+
+
+## Why
+
+I always find it harder than it should be to make a good-looking crystal figure.
+
+Traditional crystallographic tools such as VESTA are powerful, but their visual defaults often feel outdated: harsh color palettes, low-quality 3D shading, and a lot of manual tweaking before the result looks acceptable. You could import the structure into professional 3D software such as Cinema 4D or Blender, but that feels like overkill and comes with a much steeper learning curve.
+
+Pretty Lattice is my attempt to fill that gap. Built on [Three.js](https://github.com/mrdoob/three.js), it stays (relatively) lightweight without compromising visual quality. It offers a modern, intuitive interface with familiar controls researchers expect, and produces clean, aesthetically pleasing figures out of the box.
+
+## Install
+
+```shell
+pip install pretty-lattice
+```
+
+Or install as an isolated tool with [uv](https://github.com/astral-sh/uv):
+
+```shell
+uv tool install pretty-lattice
+```
+
+Requirements:
+
+- Python 3.12+
+- macOS, Linux, or Windows
+- Any modern browser
+
+## Quick start
+
+```shell
+prl gui
+```
+
+Pretty Lattice starts a local server and opens the browser automatically.
+
+Useful launch options:
+
+```shell
+prl gui --no-open     # start the server without opening a browser
+prl gui --port 8765   # use a specific port
+prl gui -p 0          # choose any free port automatically
+```
+
+## Examples
+
+### Material presets
+
+<p align="center">
+  <img src="assets/SrTiO3-material-presets.png" alt="SrTiO3 material preset examples" width="75%">
+</p>
+
+### Color scheme presets
+
+<p align="center">
+  <img src="assets/Ba2Ca2Cu3HgO8-color-schemes.png" alt="Ba2Ca2Cu3HgO8 color scheme examples" width="90%">
+</p>
+
+## License
+
+Pretty Lattice is released under the [MIT License](LICENSE).

pretty_lattice-0.1.0/README.md

@@ -0,0 +1,82 @@
+<h1 align="center"><img src="web/public/favicon.svg" alt="Pretty Lattice logo" width="30" height="30"> Pretty Lattice</h1>
+
+<p align="center">
+  Pretty Lattice is a crystal visualization tool for creating beautiful, publication-ready figures.
+</p>
+
+<p align="center">
+  <a href="https://github.com/songfeitong/pretty-lattice/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/songfeitong/pretty-lattice/ci.yml?branch=main&label=build&style=flat-square"></a>
+  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12+-3776ab?style=flat-square">
+  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green?style=flat-square">
+</p>
+
+- **Pretty**: tasteful defaults for colors, materials, lighting, and depth
+- **Simple**: an intuitive browser GUI for loading, viewing, and exporting structures
+- **Reliable**: structure parsing and analysis powered by the mature [pymatgen](https://github.com/materialsproject/pymatgen) package
+- **Scalable**: smooth interaction with systems up to 10k atoms
+- **Customizable**: tune colors, radii, materials, opacity, orientation, and export settings
+
+<p align="center">
+  <img src="assets/demo.png" alt="Pretty Lattice interface preview" width="90%">
+</p>
+
+
+## Why
+
+I always find it harder than it should be to make a good-looking crystal figure.
+
+Traditional crystallographic tools such as VESTA are powerful, but their visual defaults often feel outdated: harsh color palettes, low-quality 3D shading, and a lot of manual tweaking before the result looks acceptable. You could import the structure into professional 3D software such as Cinema 4D or Blender, but that feels like overkill and comes with a much steeper learning curve.
+
+Pretty Lattice is my attempt to fill that gap. Built on [Three.js](https://github.com/mrdoob/three.js), it stays (relatively) lightweight without compromising visual quality. It offers a modern, intuitive interface with familiar controls researchers expect, and produces clean, aesthetically pleasing figures out of the box.
+
+## Install
+
+```shell
+pip install pretty-lattice
+```
+
+Or install as an isolated tool with [uv](https://github.com/astral-sh/uv):
+
+```shell
+uv tool install pretty-lattice
+```
+
+Requirements:
+
+- Python 3.12+
+- macOS, Linux, or Windows
+- Any modern browser
+
+## Quick start
+
+```shell
+prl gui
+```
+
+Pretty Lattice starts a local server and opens the browser automatically.
+
+Useful launch options:
+
+```shell
+prl gui --no-open     # start the server without opening a browser
+prl gui --port 8765   # use a specific port
+prl gui -p 0          # choose any free port automatically
+```
+
+## Examples
+
+### Material presets
+
+<p align="center">
+  <img src="assets/SrTiO3-material-presets.png" alt="SrTiO3 material preset examples" width="75%">
+</p>
+
+### Color scheme presets
+
+<p align="center">
+  <img src="assets/Ba2Ca2Cu3HgO8-color-schemes.png" alt="Ba2Ca2Cu3HgO8 color scheme examples" width="90%">
+</p>
+
+## License
+
+Pretty Lattice is released under the [MIT License](LICENSE).

pretty_lattice-0.1.0/docs/constitution.md

@@ -0,0 +1,88 @@
+# Project Constitution
+
+## Product Definition
+
+Pretty Lattice is a **local web GUI tool** for interactive preview and rendering crystal structures as pretty, publication-ready figures.
+
+The workflow is simple:
+
+```text
+open a structure file 
+→ preview it interactively 
+→ adjust visual parameters and layouts 
+→ export a high-quality figure
+```
+
+## Why
+
+Crystal workbenches like VESTA are useful and powerful, but on the visualization and figure side, they feel somewhat outdated. The figures often don’t really feel like they belong to the 2020s. You can tweak them, but it rarely feels enough.
+
+For better visuals, people sometimes turn to C4D or Blender. But personally, I’m reluctant to learn these heavy industry tools just to make a nice crystal figure. It feels like overkill for the task.
+
+So I decided to build a lightweight tool based on modern web tech (Three.js), that can generate pretty, publication-ready figures out of the box, while still being highly configurable and providing a smooth interactive preview.
+
+## Principles
+
+- Easy to use: WYSIWYG. Easy to navigate. Intuitive interaction.
+- Yet powerful:  more control and configurations (on the visual side) than VESTA. 
+- Publication-ready:  this project is driven by my own need for publication-ready figures.
+- Focused:  Focused on viewing and rendering.  Read-only on structure file. Prepare elsewhere.
+- Modern: modern UI/UX, modern tech stack, modern asetetics.
+
+## Release Shape
+
+Developer side:
+
+```mermaid
+flowchart LR
+    A[Web source<br/>Bun + React + Three.js] --> B[Build static web assets]
+    B --> C[Bundle assets into Python package]
+
+```
+
+Users install a Python package and launch a local GUI via the command `prl gui`. This starts a local Python server and opens a browser page. The browser runs the bundled web app and uses Three.js/WebGL for rendering.
+
+```mermaid
+flowchart LR
+    D[User installs pretty-lattice]
+    D --> E[prl gui]
+    E --> F[Local browser GUI]
+```
+
+Users should **not need JS developer tools** (Node, Bun, pnpm, Vite, etc.).
+
+## Tech Stack
+
+Pretty Lattice keeps a clear backend/frontend boundary. The Python backend owns structure IO, materials analysis, and scene generation. The Web frontend owns visual interaction and rendering. The browser may use lattice-derived scene data for camera and view controls, but crystallographic or materials-analysis decisions should stay in Python unless they are purely presentational.
+
+### Backend: Python
+
+Responsibilities:
+
+- Read crystal structure files such as CIF and POSCAR.
+- Run materials analysis, including bonding, polyhedra, and symmetry.
+- Convert analyzed structures into scene specifications for the Web app.
+- Serve the local GUI and API.
+
+Stack:
+
+- Dev tools: uv, pytest, ruff
+- FastAPI + Uvicorn
+- Typer
+- Pymatgen
+- Numpy
+
+### Frontend: Web
+
+Responsibilities:
+
+- Render and interact with the scene returned by the backend.
+- Handle camera, lighting, materials, visual parameters, and browser export.
+- Keep UI state and controls close to the visual workflow.
+
+Stack:
+
+- Dev tools: Bun, Vite
+- Front-end framework: React
+- UI: Tailwind CSS, shadcn/ui, Radix, lucide
+- 3D: Three.js + React Three Fiber

pretty_lattice-0.1.0/docs/decisions/cyclic-crystal-camera-orientation.md

@@ -0,0 +1,158 @@
+# Use Cyclic Crystal Orientation for Camera Roll Zero
+
+## Status
+
+Accepted 2026-06-30.
+
+## Context
+
+Crystal camera controls need two choices:
+
+- which crystal direction is aligned to a screen axis;
+- which roll angle is treated as zero around that aligned direction.
+
+The first choice is explicit. The second choice is otherwise underdetermined:
+after one direction is fixed, the camera can still rotate freely around that
+direction.
+
+VESTA-style direct-axis views appear to use a simple cyclic convention. When a
+direct crystal axis points out of the screen, the next direct axis projects to
+screen right:
+
+```text
+a -> outward  means  b projects right
+b -> outward  means  c projects right
+c -> outward  means  a projects right
+```
+
+Pretty Lattice should use this as the default roll convention, and extend it to
+arbitrary direct-lattice view directions.
+
+## Decision
+
+Use one cyclic rule for both discrete axis presets and continuous direct-lattice
+directions.
+
+Let the direct basis be
+
+$$
+\mathbf a,\quad \mathbf b,\quad \mathbf c
+$$
+
+and let the screen basis be
+
+$$
+X=\text{right},\qquad Y=\text{up},\qquad Z=\text{outward},
+\qquad X\times Y=Z.
+$$
+
+Both bases are treated cyclically:
+
+```text
+a -> b -> c -> a
+X -> Y -> Z -> X
+```
+
+For a requested direct-lattice direction
+
+$$
+\mathbf d = u\mathbf a + v\mathbf b + w\mathbf c,
+$$
+
+define the cyclic crystal transport
+
+$$
+T(\mathbf a)=\mathbf b,\qquad
+T(\mathbf b)=\mathbf c,\qquad
+T(\mathbf c)=\mathbf a.
+$$
+
+Therefore
+
+$$
+T(\mathbf d)=u\mathbf b+v\mathbf c+w\mathbf a
+            =w\mathbf a+u\mathbf b+v\mathbf c.
+$$
+
+If the user aligns $\mathbf d$ to screen axis $S$, first normalize
+
+$$
+\mathbf p = \frac{\mathbf d}{\lVert \mathbf d\rVert}.
+$$
+
+Then use $T(\mathbf d)$ to define the next screen axis. With
+$S^+=\operatorname{next}(S)$, project the cyclic anchor into the screen plane:
+
+$$
+\Pi_{\mathbf p}(\mathbf q_0)
+  = \mathbf q_0 - (\mathbf q_0\cdot \mathbf p)\mathbf p,
+\qquad
+\mathbf q_0 = T(\mathbf d).
+$$
+
+If this projection is nonzero, normalize it:
+
+$$
+\mathbf q =
+\frac{\Pi_{\mathbf p}(\mathbf q_0)}
+     {\lVert \Pi_{\mathbf p}(\mathbf q_0)\rVert}.
+$$
+
+The camera frame is then defined by
+
+```text
+screen[S]       = p
+screen[next(S)] = q
+screen[next2(S)] is completed by the right-hand rule
+```
+
+For example, if $S=Z$, then `next(S) = X`, so the cyclic anchor becomes the
+screen-right direction. This gives:
+
+```text
+a -> Z  means  b projects to X
+b -> Z  means  c projects to X
+c -> Z  means  a projects to X
+```
+
+The same rule works for any target screen axis:
+
+```text
+a -> X  means  b projects to Y
+a -> Y  means  b projects to Z
+a -> Z  means  b projects to X
+```
+
+## Fallback
+
+If the cyclic anchor is degenerate after projection, use the direct `c` axis as
+the fallback roll reference:
+
+$$
+\mathbf q_0 = \mathbf c.
+$$
+
+If that is also degenerate, use the direct `a` axis:
+
+$$
+\mathbf q_0 = \mathbf a.
+$$
+
+Each fallback uses the same projection formula. This keeps the rule simple:
+prefer cyclic transport, otherwise keep the special vertical role of `c`, and
+only then fall back to `a`.
+
+Zero-length requested directions are invalid input and should be rejected or
+replaced by the current/default camera direction before this algorithm runs.
+
+## Consequences
+
+- Direct-axis presets and arbitrary `[u v w]` directions share one camera-roll
+  definition.
+- The discrete `a`, `b`, and `c` views match the observed VESTA-like cyclic
+  direct-axis behavior.
+- The algorithm is independent of cell angles because all projections are done
+  in Cartesian space after forming the real direct-lattice vectors.
+- The fallback is intentionally small and explainable. It treats `c` as the
+  preferred structural reference when the cyclic transport cannot determine a
+  roll angle.

pretty_lattice-0.1.0/docs/decisions/index.md

@@ -0,0 +1,7 @@
+# Decisions
+
+Architecture and product decisions that should remain easy to find.
+
+- [Keep Camera Interaction in Three.js](keep-camera-interaction-in-threejs.md)
+- [Use Cyclic Crystal Orientation for Camera Roll Zero](cyclic-crystal-camera-orientation.md)
+- [Use Pymatgen as the Python Structure Backend](use-pymatgen-backend.md)

pretty_lattice-0.1.0/docs/decisions/keep-camera-interaction-in-threejs.md

@@ -0,0 +1,99 @@
+# Keep Camera Interaction in Three.js
+
+## Status
+
+Accepted. Updated 2026-06-26 to clarify the camera snapshot and command
+boundary after the camera-direction UI work.
+
+## Plain Version
+
+We tried two mental models for preview zoom.
+
+The first model was **React-owned zoom**:
+
+```text
+wheel event
+-> compute a new viewScale in React
+-> update React state
+-> re-render the preview tree
+-> write the new zoom back to the Three.js camera
+```
+
+That was easy to wire to the zoom slider and percent input, but it made a small
+camera movement travel through a large React tree. With small structures this
+felt fine. With structures containing thousands of atoms, one scroll gesture
+could make React revisit many atoms, bonds, and polyhedra over and over.
+
+The second model is **Three.js-owned camera interaction**:
+
+```text
+wheel or drag input
+-> Three.js controls update the camera directly
+-> small UI controls read snapshots of the resulting camera state
+```
+
+This is closer to how rotation already works. The camera interaction stays
+light, and the React UI follows it instead of driving every tiny input event.
+
+## Context
+
+Pretty Lattice uses React for application UI and React Three Fiber / Three.js
+for the crystal preview. The preview can contain many renderable objects, so
+high-frequency input should avoid unnecessary React work.
+
+Rotation already felt smooth because TrackballControls changed the camera
+directly. Zoom originally took a different route because the left rail needed a
+shared value for the slider, percent input, reset, and clamp. That made the UI
+state convenient, but it also made zoom heavier than rotation.
+
+The performance issue became visible with larger structures: zoom could feel
+like it was growing while trembling, while rotation remained smooth.
+
+## Decision
+
+High-frequency camera interaction belongs in Three.js controls.
+
+TrackballControls and OrbitControls should own wheel, touch, and middle-button
+zoom behavior. React may display camera values such as view scale, primary
+direction, roll, and derived vectors, but those values are snapshots for UI, not
+the ownership path for every controls event.
+
+Bounds such as 20%-500% should be translated into Three.js camera zoom limits.
+The rail slider, percent input, and reset button may still set a target view
+scale, but after that the camera controller applies it to the camera.
+
+For camera data that needs to cross the Three.js / React boundary, use two
+separate channels:
+
+- **Snapshots:** Three.js controls publish the current camera state to narrowly
+  subscribed UI widgets. These snapshots should not live in top-level app state
+  if changing them would re-render the crystal preview tree.
+- **Commands:** UI widgets send target camera changes to the camera controller.
+  The controller applies the command directly to the camera and then publishes a
+  fresh snapshot.
+
+This boundary is the fix. Frame coalescing, epsilon tuning, and idle-delay
+adjustments can improve polish, but they should not be the primary performance
+strategy.
+
+Orientation-derived UI should follow the same rule. During an active drag,
+inertial rotation, or camera animation, controls such as the roll wheel,
+direction vectors, and linked aspect-ratio display may hold their last committed
+snapshot. Once camera motion settles, they can jump to the new committed value.
+That keeps the UI readable without moving the high-frequency camera loop into
+React.
+
+## Consequences
+
+- Rotation and zoom use the same interaction ownership model: Three.js handles
+  the fast camera movement.
+- React remains responsible for visible controls and user-facing state, but it
+  should not re-render the crystal object tree for every wheel tick.
+- The zoom rail can stay synchronized by listening to camera snapshots, while
+  rail input sends commands back to the camera controller.
+- App-level state should store low-frequency configuration and user intent, not
+  live camera snapshots that change every frame.
+- Future camera features should first ask whether they are high-frequency
+  interaction or low-frequency UI configuration. High-frequency behavior should
+  stay near the Three.js camera layer; React should subscribe to snapshots or
+  send commands across that boundary.