Metadata-Version: 2.4
Name: clayspace
Version: 0.2.0
Summary: Lightweight spatial modeling toolkit for building reusable Cells and composing worlds, with an optional mesh audit and build guard.
Author: ClaySpace contributors
License-Expression: MIT
Project-URL: Upstream lineage: Fly With Me, https://github.com/kunchenguid/fly-with-me
Keywords: clayspace,modeling,spatial,3d,blockout,worldbuilding,geometry,offline
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: licenses/FLY_WITH_ME_MIT.txt
Provides-Extra: images
Requires-Dist: Pillow>=12.3; extra == "images"
Provides-Extra: guard
Requires-Dist: numpy>=1.24; extra == "guard"
Requires-Dist: pillow>=9.0; extra == "guard"
Requires-Dist: opencv-python-headless>=4.8; extra == "guard"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: numpy>=1.24; extra == "test"
Requires-Dist: pillow>=9.0; extra == "test"
Requires-Dist: opencv-python-headless>=4.8; extra == "test"
Dynamic: license-file

# 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.

```bash
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:

```bash
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:

```bash
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:

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

Add and edit geometry:

```bash
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:

```python
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.

```bash
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):

```bash
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:

```python
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.

```bash
# 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**](https://github.com/kunchenguid/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:

```sh
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.
