All Tools

Semantic Form Sculptor

Embedding vectors to honest 3D sculptural form. The colour on every surface encodes reduction fidelity: the geometry shows structure, the colour shows how much to trust it.

Semantic Form Sculptor on GitHub

Python
Embeddings
3D Printing
Fabrication
UMAP
Sculpture

What it does

SFS takes a matrix of embedding vectors from any model and any domain (words, sentences, images, protein sequences) and runs a documented six-stage pipeline.

Pipeline

1. IngestValidate, size-check, and SHA-256 the input
2. ReduceProject from N dimensions to 3 via PCA or Isomap
3. ConfidenceCompute per-point trustworthiness: how faithfully each point's neighbourhood was preserved
4. FormBuild a mesh from the reduced point cloud
5. ColourEncode confidence as a cividis colour field on the mesh surface
6. ExportWrite PLY, STL, and 3MF, and generate a provenance manifest

Bundled corpus

A corpus of 6,000 common English words in 384-dimensional embeddings ships inside the package. The base modes run offline with no external data fetch, no API key, and no network call.

Text input and the `[embed]` extra

Six of the seven text-compatible modes consult the bundled corpus first, so common English words work immediately. Signature mode does not: it calls the live embedder unconditionally, so it always requires the [embed] extra regardless of whether the word is in the corpus.

Honest by construction

Dimensionality reduction always distorts. SFS makes that distortion visible rather than hiding it.

Surfaces are colour-mapped by trustworthiness. A high-confidence region means the visible shape faithfully represents the original neighbourhood structure. A low-confidence region means the reduction distorted those distances, and the geometry there should be read with scepticism.
A reduction-quality report (trustworthiness and continuity scores, normalised stress, and a Shepard diagram) ships alongside every form as quality_report.json. It is not a summary: it is the basis for reading the object.
Skeleton mode warns when a form exceeds the hand-fabrication strut limit (roughly 100 struts), so a piece that cannot reasonably be built by hand says so before you cut material.
A manifest.json in every output directory records every parameter, all input and output SHA-256 digests, and the reduction quality metrics. It is the complete audit trail.

Modes

Mode	Geometry	Confidence field	Input
`points`	One sphere per vector	Trustworthiness	Text word or vector file
`density`	KDE isosurface (solid)	Trustworthiness	Text word or vector file
`hull`	Convex or alpha hull	Trustworthiness	Text word or vector file
`gap`	Void between hull and alpha shape	Continuity	Text word or vector file
`shell`	Alpha shell around a concept's neighbourhood	Trustworthiness	Text word or vector file
`signature`	Deterministic displaced sphere	None (no reduction error)	Text word (always requires `[embed]` extra)
`skeleton`	Neighbourhood graph as printable struts	Edge distortion	Text word or vector file
`variance`	PCA-scaled ellipsoid with axis labels	Trustworthiness	Labelled matrix file
`loft`	Lofted surface through an ordered sequence	Sequence position	Ordered sequence file

The first seven modes (points through skeleton) accept a bare word via --text and are what sfs gallery runs by default. variance requires a labelled .npz file with a labels key. loft requires an ordered sequence file and cannot be driven from text input at all.

Install

pip install semantic-form-sculptor

# Required for signature mode, and for words outside the bundled corpus in other modes:
pip install "semantic-form-sculptor[embed]"

Requires Python 3.11 or newer. Built on dsfab, which resolves automatically from PyPI.

Usage

# Sculpt a word from the bundled corpus
sfs sculpt --text desert --mode density
sfs sculpt --text ocean --mode hull
sfs sculpt --text mountain --mode skeleton --neighbours 50

# Sculpt from a vector file
sfs sculpt vectors.npz --mode hull

# Build a vector file from a list of text strings, then sculpt it
sfs embed desert ocean forest mountain -o concepts.npz
sfs sculpt concepts.npz --mode hull

# Gallery: sculpt one word across every text-compatible mode, one specimen plate
sfs gallery desert -o desert.pdf

# Inspect: reduction fidelity report without committing to a form
sfs inspect vectors.npz

# Multi-form plate: arrange several sculpt outputs on one print-ready sheet
sfs plate sfs_out/desert sfs_out/ocean sfs_out/mountain -o comparison.pdf

# Interactive offline viewer
sfs view sfs_out/desert

Output files

Each sfs sculpt call writes a named output directory containing:

File	Purpose
`*_mesh.ply`	Coloured mesh for inspection and Blender
`*_mesh.3mf`	Watertight coloured mesh for colour 3D printing
`*_mesh.stl`	Single-body mesh for standard slicers
`legend.png`	Colormap legend
`quality_report.json`	Trustworthiness, continuity, stress, and Shepard data
`manifest.json`	Full provenance record

Design notes

Both reducers (PCA and Isomap) are deterministic given their inputs, so every run reproduces exactly.
All inputs are SHA-256 checksummed before processing. All outputs are checksummed in the same manifest.
No network calls at runtime. The bundled corpus is a static asset shipped with the package.
Path-traversal-safe file handling throughout. Unknown keys in sfs.toml are rejected with a clear error.
447 tests, approximately 90 percent coverage.

dsfab — the shared fabrication library SFS builds on
Reduction Quality Bench — standalone reduction-quality reporting
Dataset Topology Sculptor — network-graph sculpture from CSV data
All Tools