ClaySpace

ClaySpace is a lightweight spatial modeling toolkit for building places.

Make a room, a building, a street, a stage, a landscape blockout, an abstract structure, or a larger world from reusable local pieces called Cells. Keep each piece simple and portable, then place and compose those pieces into the space you need.

ClaySpace is useful when where things are matters: environment planning, background layout, continuity, shot design, collaborative worldbuilding, and spatial studies that do not need a heavyweight 3D pipeline.

python -m pip install clayspace==0.2.0

Use ClaySpace with an LLM

ClaySpace includes a compact agent guide so an LLM can learn the same Cell and world conventions the CLI uses instead of guessing at a parallel format. After installing ClaySpace, ask your coding assistant to inspect the package's LLM onboarding material, or print it directly:

clayspace llm
clayspace llm show cell-contract
clayspace llm show workflows

A typical instruction to an LLM can be as short as:

Install clayspace, read its packaged LLM onboarding guide, and use ClaySpace to build this as a portable Cell. Validate it and give me the JSON plus an HTML preview.

The LLM kit is platform-neutral. For ChatGPT, the installed ClaySpace package also contains the version-matched public Skill source. Export a fresh Skill from the package you are actually running:

clayspace llm export-chatgpt-skill --out skill.zip

Upload that skill.zip through ChatGPT's Skill interface if you want the ClaySpace workflow available as a reusable ChatGPT Skill. The Skill does not contain a second copy of the ClaySpace wheel; it points back to the public package as the executable modeling layer. After upgrading ClaySpace, export the Skill again from the upgraded package rather than keeping a hand-edited stale copy.

Make something

Start a Cell:

clayspace cell init --id MY-HOUSE --name "My house" --size 12,8,18 --out house.json

Add and edit geometry:

clayspace cell add-box house.json --id GARAGE --position 8,1.5,3 --size 6,3,7 --out house-2.json
clayspace cell add-cylinder house-2.json --id TOWER --position -4,6,0 --radius 2 --height 12 --out house-3.json
clayspace cell add-sphere house-3.json --id DOME --position -4,12,0 --radius 2.4 --out house-4.json
clayspace cell move house-4.json --id GARAGE --position 8,1.5,-2 --out house-5.json
clayspace cell preview house-5.json --out house-preview.html

preview writes a self-contained HTML view with orbit, zoom, grid, and wireframe/shaded primitive display. Open it in a modern browser and look around.

You can work directly in Python too:

from clayspace import new_box_cell, add_box, add_cylinder, save_cell

cell = new_box_cell(cell_id="MY-SET", name="My set", size=(20, 1, 20))
cell = add_box(cell, object_id="WALL-A", position=(0, 2, -8), size=(20, 4, 0.4))
cell = add_cylinder(cell, object_id="COLUMN", position=(3, 2, 0), radius=0.5, height=4)
save_cell(cell, "my-set.json")

Compose a world

Cells use their own local coordinates. A world places them with transforms, so the source Cell stays reusable.

clayspace world init --id MY-WORLD --name "My world" --out world.json
clayspace world place world.json --cell house-5.json --entity-id HOUSE-01 --position 30,0,-12 --yaw-radians 0.6 --out world-2.json
clayspace world preview world-2.json --out world-preview.html

The same building can appear more than once, move later, or be handed to someone else without rewriting its internal geometry.

Cells and geometry

The clayspace.cell.local-fragment format uses meters with x-right / y-up / z-forward coordinates. ClaySpace 0.2.0 supports:

• boxes;
• prisms with arbitrary X/Z footprints;
• cylinders;
• spheres;
• planes/cards.

Cells can also carry metadata and asset references. The validator checks that a Cell is structurally well-formed and portable.

ClaySpace also reads the earlier compact 0.1 Cell form and richer Cells that carry additional metadata, making it practical to move existing spatial work into the same composition workflow.

Check a Cell: audit and build guard (optional)

ClaySpace 0.2.0 adds an optional mesh audit and a build guard for Cells that must match locked reference plates (paintings, renders, photos):

python -m pip install "clayspace[guard]==0.2.0"
clayspace audit MY-CELL --out audit/            # multi-POV contact sheets + geometry checks
clayspace guard check MY-CELL                   # read-only: pins, plates, counts, registration, scale, audit
clayspace guard report MY-CELL --all            # per-landmark reprojection table
clayspace guard relock MY-CELL --reason "..."   # accept a re-annotated plate, with a logged reason

In a Cell's build script, wrap the build so every run is checked and must be byte-identical when replayed:

from clayspace.guard import guarded_build
guarded_build(CELL_DIR, build)    # FAIL restores the previous outputs and exits 2

All Cell-specific settings (cameras, plates, landmarks, roles, tolerances, audit profile) live in the Cell's cell-manifest.json and audit-profile.json. Full reference: clayspace llm show guard.

Film an object: orbit lookup (optional)

clayspace orbit films any clay object on a dense camera sphere so you can pull the exact angle a drawing needs instead of guessing. It uses the audit renderer and needs clayspace[guard] plus an ffmpeg binary.

# turntables every 5 deg of yaw at pitch -60..+60 every 10 deg, plus a continuous 360-frame orbit
clayspace orbit film head.obj --out head-film/ --pivot 0,1.67,-0.02 --palette palette.json
# which frame matches this drawing? (object pose + plate camera) -> nearest frames, error, reference crop
clayspace orbit lookup head-film/ --camera plate-camera.json --object-frame head-object-frame.json --crop ref.png
# smallest set of views covering many drawings within 10 deg
clayspace orbit coverage view-dirs.json --tol 10

• film takes a cell dir, a proxy.obj or an .obj file (--objects REGEX picks parts). Every pass and layer (shaded, line/def, silhouette) is encoded as a lossless mp4 under films/, then split back into every numbered PNG under frames/<pass>/<layer>/. The split is checked bit-exact against the renders. frames.json maps each frame to yaw, pitch, roll, distance and the object-space view direction. All frames share one scale (px_per_m_at_pivot) with the pivot at the image centre.
• Convention: the object faces -z, +x is its right; yaw 0 = camera in front, +yaw toward the object's right, pitch > 0 from above.
• lookup reads {"eye","look","width","height","hfov_deg"} and {"pivot","rotation"} (object -> world, columns = object axes). --crop warps the best frame to the plate's projected scale and rotation (an affine fit, so a wide lens's off-centre stretch is carried too).

Current scope

ClaySpace is early-stage modeling software focused on spatial blockout and composition: portable primitives, Cells, transforms, worlds, validation, and browser previews. Mesh import, advanced materials, rigging, sculpting, and a full desktop interface are future territory rather than the focus of this release.

Fly With Me

Part of ClaySpace's lineage comes from Fly With Me, Kun Chen's open-source browser world and flight project. That work helped establish the browser-space foundation ClaySpace grew from.

Fly With Me is MIT-licensed, copyright (c) 2026 Kun Chen. Its original license notice ships in licenses/FLY_WITH_ME_MIT.txt, with additional detail in THIRD_PARTY_NOTICES.md.

ClaySpace is released under the MIT License; see LICENSE.

Painted meshes and paper artwork (experimental)

The Python distribution includes two separate companion APIs: clayspace_painted_mesh validates local triangle/UV assets, creates native spatial proxies and generates self-contained browser previews; clayspace_paper creates finite-thickness cylindrical sleeves/arcs with source-preserving PNG attachments. They do not introduce a native Cell mesh primitive or arbitrary-surface wrapping.

Install image support and run a reproducible example outside the source tree:

python -m pip install 'clayspace[images]==0.2.0'
python -m clayspace_paper.example --out paper-example --hd-size 512

Open paper-example/quick-preview.html in a browser. The example generates its own neutral front/back artwork, preserves its PNG bytes, builds two placed paper arcs and writes local Cells, world data, diagnostics, atlases and offline previews. No Node installation is required for this Python example. A 2048 atlas is supported, but atlas chart allocation and resampling do not imply one-to-one source pixels. Pillow is optional; native modeling has no mandatory third-party dependencies. Audit/guard and the orbit/parts/layering tools use clayspace[guard]. Orbit movie encoding also requires FFmpeg, installed separately.

The standalone JavaScript form-cover, crease and two-link contact helpers are not part of this Python distribution. Their separate experimental package does not provide a Python motion bridge. No motion bridge, general walking controller, physical paper simulation or guaranteed whole-motion bound is supplied here.