Reference

Project

The workspace, what is planned, and what is known not to work yet.

1Workspace

Pleochroma is a Cargo workspace of libraries and applications, all MIT licensed. The libraries are published on crates.io, with their API documentation on docs.rs.

Crate	Kind	Description	Published
`pleochroma`	library	A physically-based spectral gemstone renderer that turns GemCAD-style cutting instructions into rendered output.	crates.io · docs.rs
`pleochroma-cut-core`	library	Editor-core library for faceting cutting instructions: preform, tiers (including concave tiers and angle relations), undo/redo, and live solid validation.	crates.io · docs.rs
`pleochroma-solid`	library	Pure-CPU solid rasterizer and 2D faceting diagram for a design's solid mesh, plus the pure replan planner. No GUI toolkit, no threads, no filesystem. Shared by the desktop editor and the web app.	crates.io · docs.rs
`pleochroma-editor`	library	GUI-free faceting-design editor logic shared by the desktop editor and the web app: the editor session (design, undo/redo, selection, dirty tracking), tier, preform and material form parsing, plain-struct view models, the cutting sheet, Retarget, Deep Solve, variants, the guided walkthrough and tutorials, cutting mode, the angle sweep, the overall verdict and the solve policy. No GUI toolkit, no threads, no clock, no filesystem.	crates.io · docs.rs
`pleochroma-formats`	library	Readers and writers for gemstone faceting design file formats.	crates.io · docs.rs
`pleochroma-vault`	library	SQLite-backed storage, data models, and local import/export for gemstone faceting design libraries.	crates.io · docs.rs
`pleochroma-net`	library	Wire protocol for offloading pleochroma spectral ray samples to a remote render worker: scene-state and radiance-buffer codecs, message framing, a build-compatibility handshake, and the TLS helpers and enrollment client shared by the viewer and the worker. It runs no server and opens no listening sockets.	crates.io · docs.rs
`pleochroma-dispatch`	library	Sample-range scheduling for render lanes: a shared disjoint sample cursor, per-lane rate models, a lane pool that merges chunk sums deterministically, and a whole-item batch queue. No networking and no GUI types.	crates.io · docs.rs
`pleochroma-render-jobs`	library	Render jobs: the frozen job file (scene, material, lighting, camera and export settings) shared by the desktop render queue and the command-line renderer, the job state machine, queue ordering, and the shell and PowerShell script writer.	crates.io · docs.rs
`pleochroma-update`	library	New-version check of the Pleochroma apps against the GitHub releases (`v<version>` tags).	crates.io · docs.rs
`pleochroma-cut`	app (desktop)	Desktop faceting-design editor: library browsing, spectral 3D rendering, material retargeting, and a solid inspection view.	crates.io · docs.rs
`pleochroma-worker`	app (CLI / server)	The coordinator (`serve`): serves a pleochroma-backed design catalogue over mutual TLS and accepts joining render workers. The optional `worker` feature adds render capacity — `serve --render`, `join` to work for a coordinator, and `render`, a one-shot scene-to-PNG CLI. A coordinator that renders itself also keeps still-picture jobs for clients that disconnect.	crates.io · docs.rs
`pleochroma-cli`	app (CLI)	Headless command-line tool for faceting designs: `info`, `solve`, `metrics`, `validate`, `optimize`, `retarget`, `sweep` and `export`, from scripts, with no window and no GPU. Each of them takes any number of design files, and `--out-dir` writes one result per design. Reads `.psdd`, `.asc`, `.gem` and `.gcs` and uses the same solver, retarget gate and optimizer as the desktop editor. Its `render` and `tilt-video` commands run saved render job files.	crates.io · docs.rs
`pleochroma-web`	app (browser)	Browser build of pleochroma, served as static files: open or start a design (`.psdd`, `.asc`, `.gem`, `.gcs`), edit it in the same faceting CAD engine, and look at it as a solid, a faceting diagram and a spectral render traced on your CPU cores in Web Workers (and on the GPU for isotropic stones in Chrome and Edge), with the brilliance, fire, windowing and extinction figures and the tilt curve. Files are read and saved as browser downloads; the design is kept in the browser's own storage, so a reload brings it back. No design library, remote rendering, Deep Solve or database. See the web app page.	crates.io · docs.rs
`pleochroma-web-core`	library	The compute side of the browser build with no DOM and no GUI in it: the Web Worker protocol, the scene spec that builds the desktop's exact render scene, the CPU chunk tracer and its bit-exact accumulation, the worker-side solve, Optimize, metrics and tilt sweeps, and the logic of the GPU admission and start-up test. Tested natively.	crates.io · docs.rs
`pleochroma-web-compute`	app (Web Worker)	The Web Worker entry point of the browser build: decodes a message, runs the `pleochroma-web-core` handler, posts the reply.	crates.io · docs.rs
`pleochroma-web-gpu`	app (Web Worker)	The WebGPU render Worker of the browser build: decodes a message, runs event-wavefront GPU rendering and posts the reply. Built by Trunk as a worker next to `pleochroma-web`.	not published
`pleochroma-mobile-core`	library	The interface-free core of the mobile app: the local design library, the shared editor session, settings, the cutting-instruction rows, the property and check models, the render pool with its battery and thermal governor, history and variants, Deep Solve, Optimize and Retarget jobs, concave editing, the remote-rendering client (interactive sessions and durable server jobs), and the `Platform` trait that hides what the operating system provides (files, sharing, printing, clipboard, keep-awake, thermal state). No interface toolkit and no Android code; tested natively against a mock platform.	crates.io · docs.rs
`pleochroma-mobile-android`	app (Android)	The phone and tablet app: a touch-first Slint interface over `pleochroma-mobile-core`, packaged as a Gradle project with a thin Kotlin `NativeActivity` shim. Library, design editing (tiers, concave tiers, stone, light, checks), solid, diagram and render views (on the device or on a coordinator or worker), history and variants, Deep Solve, Optimize, Retarget, cutting mode and server jobs. The same interface also runs in a desktop window as a preview. Built from source and not in an app store. See the mobile app page.	crates.io · docs.rs

2Roadmap

PLANNED, NOT IMPLEMENTED

Everything in this section is a plan, not a feature. None of it exists in the current source tree, none of it has a release date, and the order below is not a promise of sequence. It is listed so that the direction of the project is visible. Features that have since landed, such as planning stones from a 3D scan of the rough, taking the color of the rough from photos, cutting concave facets, the optical-effect overlays and rendering on a coordinator from the Android app, are described on the other pages and no longer appear here.

Planned feature	What it will do	Builds on
Optical-effect overlays in the web and Android apps	The desktop studio can mark windowing, extinction, brilliance and fire over the live render (Optical Diagnostics). The web and Android apps have no overlay yet. The overlay’s analysis and compositing are free of desktop code so that those apps can adopt it, and a GPU version of its analysis pass is a possible later step.	The analytic ray classifier and image sampler in the `pleochroma` crate (`color/metrics`) and its overlay compositor (`renderer/optical_overlay.rs`).
Mobile app: help, tutorials and a store release	Add the manual, a first-run walkthrough and tutorials to the Android app (its Help page says they arrive in a later version), and list the app in an app store. It is not in an app store yet: you build it from source. A store listing is not scheduled.	The studio’s manual and tutorials (studio page) and the app’s existing `Platform` split (`pleochroma-mobile-core`).
GPU rendering beyond the current Path-Traced browser material limits	The web app tests the GPU while the page loads and renders isotropic stones such as diamond and spinel on it in Chrome and Edge (on by default, and it falls back to the CPU workers with the reason on any problem). Birefringent and color-zoned stones still render on the CPU workers. Extending the GPU to birefringent and color-zoned stones is not promised; it depends on kernels small enough for a browser to compile safely.	The GPU compute path and its equivalence harness (physics page), and the browser build’s CPU worker pool (web app page).
Multi-language support	The desktop studio and the web app in more languages than English: menus, dialogs, messages and the guided walkthrough, with a language picker, plus the printed cutting instructions and faceting diagram labels in the chosen language.	The Slint interface toolkit’s built-in translation support, which both applications already use; today every text in them is English only and none of it is marked for translation yet.
More database adapters	Keep the design library in the database you already run: MySQL, PostgreSQL or another server, alongside the built-in SQLite file, so a workshop or club can share one library.	The library storage in `pleochroma-vault`, which today writes a local SQLite database.

3Status and limitations

pleochroma-web is the browser build (live.pleochroma.com, described on the web app page). It renders on CPU Web Workers (slower than the desktop’s GPU path, so a few hundred samples take a while on a laptop) and, for isotropic stones in Chrome and Edge, on the GPU: the page tests the GPU while it loads and says what it renders with. It edits and solves designs with the same engine as the desktop, and keeps the design you are working on in this browser (so a reload brings it back), but it is not a store, so save your work as downloads. It has no design library, remote rendering or Deep Solve, no tutorials, cutting mode, variants or command palette, and its concave tiers are listed but cannot be edited — see the web app page and its own README.md for the limits.
The Android app (apps/pleochroma-mobile-android, described on the mobile app page) is not in an app store: you build it from source and install it on your own device, or run its interface in a desktop window. It renders on the device (on its GPU for pictures up to 512 × 512 pixels, otherwise on its processor) or on a coordinator or worker it has enrolled with. It has history and variants, Deep Solve, concave editing, Optimize and Retarget, but no Rough planner, tutorials or help yet. Optimize and Retarget are included by the default validated-design-search feature. There is no screen-reader support yet, because the interface toolkit exposes no accessibility tree on Android. Its README.md lists the other known limits.
The GPU compute path requires a Vulkan, DirectX 12 or Metal adapter (OpenGL is left out on the desktop on purpose; WGPU_BACKEND=gl tries it at your own risk) with at least 11 storage buffers per shader stage (MEGAKERNEL_STORAGE_BUFFERS, crates/pleochroma/src/renderer/gpu/context.rs); without one, rendering falls back to the CPU tracer. A concave stone is traced on the GPU with all of its up to 128 tool placements (GPU_MAX_TOOL_PRIMITIVES, crates/pleochroma/src/geometry/tool/pack.rs), locally, on a remote worker and in the browser.
Concave tiers have limits. Every tool placement is sized from the finished flat stone’s width W (the same W as the cutting sheet’s L/W), so concave edits never change the stone’s width, length or height. The optimizer’s yield and optics, the angle sweep, Retarget and the library previews use the stone with its tools, but the optimizer’s shape penalty (the table percent and the crown-to-pavilion ratio) reads the flat stone. Deep Solve declines a design with concave tiers. A concave tier cannot be frosted.
Frosted tiers and facets render matte in the studio, the library previews, exports, render jobs and remote renders, and the tilt curves follow them. The live Checks numbers, the optimizer, Retarget and Compare still score every facet as polished. A .asc file cannot hold frosting (the editor says so on export; .psdd and .gcs files keep it). The web and Android apps load, save and render frosting but only offer the Frosted Girdle switch, not frosting a tier or a facet.
The Rough planner reads rough meshes as OBJ, STL (ASCII or binary) or PLY (ASCII or binary), up to 64 MiB, in a unit you choose (it suggests one when the size looks wrong but never applies it). Small scan defects are repaired on import: hair-wide gaps, faces turned the wrong way and holes whose edge loop is up to 5 % of the bounding-box diagonal long (at most 64 edges). A smooth scan is planned from the scan itself, with a simplified outline of at most 64 planes only for the grid, and every stone is still checked against the real scan; a scan plan stops at a time limit (120 s by default, shown as “Stopped at the time limit”) and shows the best layouts found. A mesh with more than 200,000 triangles, an open scan with bigger holes, or a mesh that crosses itself falls back to its convex outline with a note, except a smooth scan, which is refused (decimate it first). Inclusions can be added as closed meshes (or located from photos on a fixed camera rig); stones keep clear of them with a margin, while the weight and the yield count them as material. An inclusion that reaches the surface is refused, and inclusions on a block, cylinder or pebble rough are not available yet.
The .gcs export (editor, browser build and pleochroma-cli) is experimental: its files have not yet been opened in Gem Cut Studio.

Ray-Traced and Path-Traced

Ray-Traced is available on desktop, browser, Android and remote workers, with CPU and GPU rendering. It supports every material class as a fixed-index approximation. Browser Path-Traced anisotropic GPU support remains a separate future task.

Ray-Traced is a deterministic approximation: one d-line index, or three fixed indices with Fire, RGB absorption tint and 1/4/8/16 AA taps. It finishes at the tap count without denoising. It omits polarization, birefringent doubling, scattering, zoning and edge rounding. Path-Traced retains the spectral model. Optical metrics, tilt sweeps and diagnostics keep their separate analytic tracer.