Skip to main content

3d-review

3d-review

3d-review is what I used to review a 3D design together with an AI assistant, while designing a 3D-printed toy. The person shows what is wrong on the model itself, the assistant answers with pictures, and the assistant has to prove that what the person asked for is still true after every rebuild.

It has four parts, and each one can be used alone.

  • The bench is a web page that shows the model's stages. The person picks a part, moves or turns a ghost of it, marks a spot, writes what is wrong and submits. Each submission keeps the before and after pictures, the exact transform and the words, and becomes a thread the assistant answers. Replies are drawn from the person's own camera, lens and frame, so they line up with the person's picture, and what is no longer there shows as an orange shadow. "Publish all" notifies the assistant once for everything new.
  • The ledger records which step of a build pipeline moved or rebuilt a part the person cares about, including code that runs between two steps. A placement the person locked stays locked, or the ledger says which line moved it.
  • The board has one row per thing the person asked for, each with a measurement and a bar. A planted fault proves each row can go red, so a green board is not a green check over a hole.
  • The Penpot bridge pushes 2D outlines in millimetres into a self-hosted Penpot file and reads the person's edits back.

Install

pip install 3d-review
pip install "3d-review[penpot]"    # adds shapely, for cutting outlines in the Penpot bridge

In Python it is imported as review3d. It uses 3d-base for pictures.

The bench

3d-review stages body.stl arm.stl wheel.stl -o model     # writes model/stages.json and model/stages/parts.glb
cp "$(python -c 'import review3d,os;print(os.path.dirname(review3d.__file__))')/bench/bench.example.toml" model/bench.toml
3d-review bench --config model/bench.toml --port 8766

Then open http://localhost:8766/twist.html. threads.html lists every thread. From Python, review3d.stages.write_stages writes any number of stages (for example "parts", "assembled" and "printed") from {stage: {part: trimesh.Trimesh}}, and review3d.bench.server.Bench takes your own notifier, rebuild hook and freshness check. The default notifier appends a line to a file, so the assistant can watch that file.

Pictures that keep themselves current. review3d.fresh tells whether a picture or a stage file was made from the code that would make it now, by a content hash of the files it was built from (found by reading the builder's imports), so a touched or reverted file does not count as a change and a changed file copied back with an old date does. review3d.bench.watch.Watcher rebuilds whatever has fallen behind in the background, waits while the code is still being edited or while a hold file is fresh, and its status is what /api/fresh serves.

The bench never changes the model. A submission is a request, and applying it is a separate step.

The ledger

from review3d import ledger
import mybuild

ledger.install(mybuild, watch={"arm", "wheel"}, pipeline="build")
mybuild.build()
print(ledger.missing(mybuild, "build"))   # steps the pipeline calls that the ledger does not wrap
ledger.write("ledger.json")

The steps are read from the pipeline's own source, so a step added later is never invisible to it. Moves are measured exactly (the rigid transform between the vertices before and after), and a part whose vertex count changed is reported as rebuilt.

The board

import types
import trimesh
from review3d.board import Board, Row, at_most, mirror_asymmetry

design = types.SimpleNamespace(body=trimesh.load("part.stl"))   # any object your rows can read

board = Board([Row("symmetric", "the two sides match", lambda d: mirror_asymmetry(d.body, normal=(1, 0, 0)), at_most(0.2), "mm")])

@board.fault("symmetric")
def bump(design):
    lump = trimesh.creation.box(extents=(2, 2, 2))
    lump.apply_translation([6, 0, 0])
    design.body = trimesh.util.concatenate([design.body, lump])

board.report(design)
print(board.proof_table(board.prove(design)))

A row whose measurement fails or has no input reads unknown, never green. A row with no fault reads unproven. The measurements include mirror symmetry, sphericity, surface roughness, gap and penetration between parts, tipping, first-layer area, overhang share, length along an axis, axis angle, bow, out of round, tunnels, and the brightness of a rendered view.

The Penpot bridge

from review3d.penpot import PenpotClient, PenpotSettings

client = PenpotClient(PenpotSettings.load("penpot.toml"))   # or PENPOT_* environment variables
result = client.push({"plate": [(0, 0), (60, 0), (60, 20), (0, 20)]})
edited = client.pull(file_id=result.file_id)

One Penpot unit is one millimetre. Keep credentials in the settings file or the environment, never in code.

Claude Code skill

3d-review skill            # copies it to ~/.claude/skills/3d-review

The skill is the review loop as we ran it. It covers writing the person's requirements as rows before building, proving each row, answering threads with pictures, keeping locks through rebuilds, asking questions with pictures on the bench instead of in words, and the failures that taught each rule.

Limits

  • The bench is meant for one person and one assistant on a trusted network. It has no login, so keep it on 127.0.0.1 or behind a private network.
  • The board's measurements are general. The rows that matter for your design are yours to write.
  • The bench includes three.js r169 (MIT, licence in bench/static/vendor).
  • Reading through Penpot's exporter depends on the exporter service working. The default pull reads the stored geometry and does not need it.

Development

python -m venv .venv && .venv/bin/pip install -e '.[test,penpot]'
.venv/bin/pytest

The Penpot tests use a fake server. Set PENPOT_URL and a token to run the live round trip too.

License

MIT

Metadata

Release files for 3d-review 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for 3d-review 0.4.1
File Size Uploaded Provenance Actions
3d_review-0.4.1.tar.gz 418.1 kB With provenance Details for 3d_review-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for 3d-review 0.4.1
File Interpreter ABI Platform Actions
3d_review-0.4.1-py3-none-any.whl Python 3 none any Details for 3d_review-0.4.1-py3-none-any.whl

Total release size: 822.6 kB

Release files / 3d_review-0.4.1.tar.gz

Download URL 3d_review-0.4.1.tar.gz
Size 418.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c002074dfbbdc73d8eecd373e39274a1f3f1edc118c1d79464b0e532b83d751b
BLAKE2b-256 checksum
How to use checksums
cce7d54249c42e450b23d28001165fd4c88eb528ec7848e67ac87c34d5aa32ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / 3d_review-0.4.1-py3-none-any.whl

Download URL 3d_review-0.4.1-py3-none-any.whl
Size 404.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
617a0d3d4775be9baf0fd658e546803ae713ee5e38b946ff600c90fef7f1d4d6
BLAKE2b-256 checksum
How to use checksums
77cba35d9c844b2f07dda3ba6159baf13a48745f2c1d6e6168bb20f5fb56d20a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for 3d-review 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for 3d_review-0.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page