Semantic Form Sculptor

Turn high-dimensional embedding vectors into honest, printable 3D sculptures. Each form carries its reduction fidelity as colour: the geometry shows structure, the colour shows how much to trust it.

Quickstart

pip install semantic-form-sculptor
sfs sculpt --text desert --mode density

Two commands from a clean Python environment to a print-ready mesh. The bundled corpus covers common English words, so there is no data file, no API key, and no network call.

Install

pip install semantic-form-sculptor               # core: bundled corpus, all form modes
pip install 'semantic-form-sculptor[embed]'      # add fastembed for words outside the corpus

As a standalone tool:

pipx install semantic-form-sculptor

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 pipeline:

1. Ingest: validate, size-check, and SHA-256 the input
2. Reduce: project from N dimensions to 3 via PCA or Isomap
3. Confidence: compute per-point trustworthiness, how faithfully each point's neighbourhood was preserved
4. Form: build a mesh from the reduced cloud
5. Colour: encode confidence as a cividis field on the mesh surface
6. Export: write PLY, STL, 3MF, and GLB, and generate a provenance manifest

The colour is not decoration. A high-confidence region means the visible shape at that location 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.

Modes

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

File-based modes (points, density, hull, gap, variance, skeleton, loft) take a vector file as input. Concept modes (shell, signature) take a label resolved against an embedding store, a --text word, or a --vector file. loft expects an ordered sequence in its input file.

Text input, no file needed

Common English words work immediately from the bundled corpus, using --text:

sfs sculpt --text desert --mode density
sfs sculpt --text ocean --mode hull
sfs sculpt --text mountain --mode skeleton --neighbours 50

For words or phrases outside the corpus, add the [embed] extra:

sfs sculpt --text "climate change" --mode density

Build a labelled vector file from text strings, then sculpt it:

sfs embed desert ocean forest mountain -o concepts.npz
sfs sculpt concepts.npz --mode hull

Gallery plate

Sculpt a word in every text-compatible mode and lay them out on one specimen plate:

sfs gallery desert -o desert.pdf

Inspect before committing

Check reduction fidelity without building a mesh:

sfs inspect vectors.npz

Prints trustworthiness and continuity scores and writes a quality report with a Shepard diagram.

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
sfs plate sfs_out/justice --views ortho --dpi 300 -o justice.png

View

Open the interactive offline viewer for any sculpt output directory:

sfs view sfs_out/desert

Configuration

Place sfs.toml in the working directory, or pass --config path/to/config.toml:

[sfs]
reducer = "pca"
colormap = "cividis"
kde_bandwidth = 0.3
alpha = 0.4
seed = 42

Unknown keys are rejected with a clear error. All parameters have documented defaults.

Determinism and provenance

Every run is reproducible and auditable:

• Both reducers (PCA and Isomap) are deterministic given their inputs, so every run reproduces exactly.
• A fixed seed is recorded in the manifest for reproducibility.
• All inputs are SHA-256 checksummed before processing, and the digest is written to the manifest.
• All outputs are SHA-256 checksummed in the same manifest.
• The manifest records every parameter: reducer, confidence mode, colormap, domain, scale factor, seed, and reduction quality metrics.
• No network calls at runtime. The bundled corpus is a static asset shipped with the package.

The manifest.json in every output directory is the complete audit trail.

Output files

Each sfs sculpt call writes an output directory:

File	Purpose
*_mesh.ply	Coloured mesh (inspection, Blender)
*_mesh.3mf	Watertight coloured mesh (colour 3D print)
*_mesh.stl	Single-body mesh (standard slicer)
*_mesh.glb	3D viewer asset
viewer.html	Offline three.js viewer (open from file://)
legend.png	Colormap legend
quality_report.json	Trustworthiness, continuity, stress, Shepard data
manifest.json	Full provenance record

License

MIT