Metadata-Version: 2.4
Name: semantic-form-sculptor
Version: 0.1.1
Summary: Turn high-dimensional embeddings into 3D printed sculptures with honest fidelity colour.
Author-email: Sean Patrick Morris <pfn.sean@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/datasculptures/semantic-form-sculptor
Project-URL: Repository, https://github.com/datasculptures/semantic-form-sculptor
Project-URL: Bug Tracker, https://github.com/datasculptures/semantic-form-sculptor/issues
Keywords: embeddings,dimensionality-reduction,sculpture,fabrication,datasculptures
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.1
Requires-Dist: scipy>=1.12
Requires-Dist: scikit-learn>=1.4
Requires-Dist: click>=8.1
Requires-Dist: matplotlib>=3.8
Requires-Dist: pyarrow>=14.0
Requires-Dist: safetensors>=0.4
Requires-Dist: trimesh>=4.0
Requires-Dist: scikit-image>=0.26
Requires-Dist: open3d>=0.18
Requires-Dist: umap-learn>=0.5
Requires-Dist: dsfab>=0.1.0
Requires-Dist: manifold3d>=3.5
Requires-Dist: shapely>=2.0
Provides-Extra: embed
Requires-Dist: fastembed>=0.4; extra == "embed"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: fixtures
Requires-Dist: rqb; extra == "fixtures"
Dynamic: license-file

# Semantic Form Sculptor

![Semantic Form Sculptor: forms sculpted from words](SFS-Forms.png)

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
