clayspace 0.1.1__tar.gz

clayspace-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClaySpace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clayspace-0.1.1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: clayspace
+Version: 0.1.1
+Summary: Standalone local spatial modeling toolkit for building portable Cells and worlds on your own computer.
+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
+Dynamic: license-file
+
+# ClaySpace
+
+**ClaySpace is a standalone spatial modeling toolkit you can install on your
+own computer and use without an account, hosted service, or host-world SDK.**
+Build a room, a building, a street, a stage, a landscape
+blockout, an abstract structure, or a whole world from portable local pieces
+called **Cells**.
+
+ClaySpace is intentionally lightweight. Its job is to give geometry stable
+identity, coordinates, placement, and a viewable spatial structure without
+forcing a particular art pipeline or story system on top of it.
+
+> **Upstream license notice:** ClaySpace's development lineage includes
+> [Fly With Me](https://github.com/kunchenguid/fly-with-me) by Kun Chen, used
+> under the MIT License. The original `Copyright (c) 2026 Kun Chen` notice and
+> MIT terms are included with this distribution in
+> `licenses/FLY_WITH_ME_MIT.txt`. ClaySpace is an independent project and is
+> not maintained or endorsed by the Fly With Me project.
+
+```bash
+python -m pip install clayspace==0.1.1
+```
+
+There are no required runtime dependencies and no network calls in the core
+package.
+
+## Make something
+
+Start a local Cell:
+
+```bash
+clayspace cell init --id MY-HOUSE --name "My house" --size 12,8,18 --out house.json
+```
+
+Add and edit primitive 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 file** with a dependency-free orbit,
+zoom, grid, and wireframe/shaded primitive viewer. Open it in any modern
+browser. Nothing is uploaded anywhere.
+
+You can also work directly in Python:
+
+```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 stay local and portable. A **world** places them with transforms without
+rewriting the Cell itself.
+
+```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
+```
+
+That separation means the same building can be placed many times, moved, or
+shared without baking any one world's coordinates into the source object.
+
+## Cells and geometry
+
+The public `clayspace.cell.local-fragment` format uses meters with
+`x-right / y-up / z-forward` coordinates. 0.1.1 supports these procedural
+primitives:
+
+- boxes;
+- prisms with arbitrary X/Z footprints;
+- cylinders;
+- spheres;
+- planes/cards.
+
+Cells may also carry additional metadata and asset references. The validator
+checks structural portability; it is not a structural-engineering, collision,
+or mesh-quality certification system.
+
+For compatibility, ClaySpace also reads the earlier compact `0.1` Cell form and
+richer production Cells that carry extra host metadata. Host-specific fields do
+not become part of ClaySpace policy.
+
+## What ClaySpace does *not* require
+
+You do **not** need:
+
+- another project's SDK;
+- a cloud account;
+- a ledger or database service;
+- a server;
+- a particular renderer;
+- permission from a host system to make your own Cells and worlds.
+
+Other projects can choose to depend on ClaySpace. ClaySpace itself does not
+depend on their identity, workflow, publication, or governance systems.
+
+## Fly With Me provenance and license
+
+ClaySpace's development lineage includes
+[**Fly With Me**](https://github.com/kunchenguid/fly-with-me), the open-source
+browser world/flight project by **Kun Chen**. Fly With Me is licensed under the
+MIT License, copyright (c) 2026 Kun Chen. Its original MIT notice is included
+verbatim in `licenses/FLY_WITH_ME_MIT.txt` and described in
+`THIRD_PARTY_NOTICES.md`.
+
+We are deliberately explicit about that origin. ClaySpace is an independent
+project and is not maintained or endorsed by Kun Chen or the Fly With Me
+project.
+
+The ClaySpace package itself is also released under the MIT License; see
+`LICENSE`.
+
+## Current scope
+
+ClaySpace 0.1.1 is an early modeling/blockout release, not a replacement for a
+full DCC such as Blender. It provides portable spatial primitives, Cell/world
+composition, transforms, validation, and local browser previews. Mesh import,
+advanced materials, rigging, sculpting, and a full desktop GUI are not part of
+this release.

clayspace-0.1.1/README.md

@@ -0,0 +1,130 @@
+# ClaySpace
+
+**ClaySpace is a standalone spatial modeling toolkit you can install on your
+own computer and use without an account, hosted service, or host-world SDK.**
+Build a room, a building, a street, a stage, a landscape
+blockout, an abstract structure, or a whole world from portable local pieces
+called **Cells**.
+
+ClaySpace is intentionally lightweight. Its job is to give geometry stable
+identity, coordinates, placement, and a viewable spatial structure without
+forcing a particular art pipeline or story system on top of it.
+
+> **Upstream license notice:** ClaySpace's development lineage includes
+> [Fly With Me](https://github.com/kunchenguid/fly-with-me) by Kun Chen, used
+> under the MIT License. The original `Copyright (c) 2026 Kun Chen` notice and
+> MIT terms are included with this distribution in
+> `licenses/FLY_WITH_ME_MIT.txt`. ClaySpace is an independent project and is
+> not maintained or endorsed by the Fly With Me project.
+
+```bash
+python -m pip install clayspace==0.1.1
+```
+
+There are no required runtime dependencies and no network calls in the core
+package.
+
+## Make something
+
+Start a local Cell:
+
+```bash
+clayspace cell init --id MY-HOUSE --name "My house" --size 12,8,18 --out house.json
+```
+
+Add and edit primitive 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 file** with a dependency-free orbit,
+zoom, grid, and wireframe/shaded primitive viewer. Open it in any modern
+browser. Nothing is uploaded anywhere.
+
+You can also work directly in Python:
+
+```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 stay local and portable. A **world** places them with transforms without
+rewriting the Cell itself.
+
+```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
+```
+
+That separation means the same building can be placed many times, moved, or
+shared without baking any one world's coordinates into the source object.
+
+## Cells and geometry
+
+The public `clayspace.cell.local-fragment` format uses meters with
+`x-right / y-up / z-forward` coordinates. 0.1.1 supports these procedural
+primitives:
+
+- boxes;
+- prisms with arbitrary X/Z footprints;
+- cylinders;
+- spheres;
+- planes/cards.
+
+Cells may also carry additional metadata and asset references. The validator
+checks structural portability; it is not a structural-engineering, collision,
+or mesh-quality certification system.
+
+For compatibility, ClaySpace also reads the earlier compact `0.1` Cell form and
+richer production Cells that carry extra host metadata. Host-specific fields do
+not become part of ClaySpace policy.
+
+## What ClaySpace does *not* require
+
+You do **not** need:
+
+- another project's SDK;
+- a cloud account;
+- a ledger or database service;
+- a server;
+- a particular renderer;
+- permission from a host system to make your own Cells and worlds.
+
+Other projects can choose to depend on ClaySpace. ClaySpace itself does not
+depend on their identity, workflow, publication, or governance systems.
+
+## Fly With Me provenance and license
+
+ClaySpace's development lineage includes
+[**Fly With Me**](https://github.com/kunchenguid/fly-with-me), the open-source
+browser world/flight project by **Kun Chen**. Fly With Me is licensed under the
+MIT License, copyright (c) 2026 Kun Chen. Its original MIT notice is included
+verbatim in `licenses/FLY_WITH_ME_MIT.txt` and described in
+`THIRD_PARTY_NOTICES.md`.
+
+We are deliberately explicit about that origin. ClaySpace is an independent
+project and is not maintained or endorsed by Kun Chen or the Fly With Me
+project.
+
+The ClaySpace package itself is also released under the MIT License; see
+`LICENSE`.
+
+## Current scope
+
+ClaySpace 0.1.1 is an early modeling/blockout release, not a replacement for a
+full DCC such as Blender. It provides portable spatial primitives, Cell/world
+composition, transforms, validation, and local browser previews. Mesh import,
+advanced materials, rigging, sculpting, and a full desktop GUI are not part of
+this release.

clayspace-0.1.1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+## Fly With Me
+
+ClaySpace's development lineage includes **Fly With Me**, an open-source browser
+world/flight project by **Kun Chen**:
+
+https://github.com/kunchenguid/fly-with-me
+
+Fly With Me is distributed under the MIT License, copyright (c) 2026 Kun Chen.
+The original license text is preserved verbatim in
+`licenses/FLY_WITH_ME_MIT.txt`.
+
+ClaySpace is an independent project. Kun Chen and the Fly With Me project do
+not maintain, sponsor, or endorse ClaySpace.
+
+The public ClaySpace Python package is licensed separately under its own MIT
+License. The Fly With Me notice remains included to preserve the upstream
+license and make the project's provenance explicit.

clayspace-0.1.1/clayspace/__init__.py

@@ -0,0 +1,14 @@
+from .cell import inspect_cell, load_cell, new_box_cell, save_cell, validate_cell
+from .model import add_box, add_cylinder, add_plane, add_prism, add_sphere, move_geometry, recompute_bounds, remove_geometry
+from .placement import make_placement, validate_placement
+from .preview import preview_cell, preview_world
+from .resources import manifest, schema
+from .world import inspect_world_snapshot, load_world_snapshot, new_world, place_cell, save_world_snapshot, validate_world_snapshot
+
+__version__ = "0.1.1"
+__all__ = [
+    "inspect_cell","load_cell","new_box_cell","save_cell","validate_cell",
+    "add_box","add_cylinder","add_plane","add_prism","add_sphere","move_geometry","recompute_bounds","remove_geometry",
+    "make_placement","validate_placement","preview_cell","preview_world","manifest","schema",
+    "inspect_world_snapshot","load_world_snapshot","new_world","place_cell","save_world_snapshot","validate_world_snapshot",
+]

clayspace-0.1.1/clayspace/cell.py

@@ -0,0 +1,232 @@
+"""Standalone local Cell ownership: creation, validation, inspection and safe I/O.
+
+ClaySpace Cells are host-agnostic local geometry. Host projects may attach their
+own workflow metadata, but ClaySpace itself does not define canon, acceptance,
+publication, identity or ledger policy.
+"""
+from __future__ import annotations
+import json
+from copy import deepcopy
+from math import isfinite
+from pathlib import Path, PurePosixPath
+from typing import Any
+from zipfile import ZipFile, is_zipfile
+
+MAX_CELL_BYTES = 16 * 1024 * 1024
+
+
+def _finite(v: Any) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool) and isfinite(v)
+
+
+def _vector(v: Any, n: int = 3) -> bool:
+    return isinstance(v, (list, tuple)) and len(v) == n and all(_finite(x) for x in v)
+
+
+def _text(v: Any) -> bool:
+    return isinstance(v, str) and bool(v.strip())
+
+
+def _object(v: Any) -> dict:
+    return v if isinstance(v, dict) else {}
+
+
+def _absent(v: Any) -> bool:
+    return v is None or v == 'none'
+
+
+def load_cell(path: str | Path) -> dict:
+    """Load JSON or the sole cell.json in a ZIP, without extracting/running files."""
+    path = Path(path)
+    if is_zipfile(path):
+        with ZipFile(path) as archive:
+            candidates = []
+            for item in archive.infolist():
+                parts = PurePosixPath(item.filename)
+                if parts.name != 'cell.json' or item.is_dir():
+                    continue
+                if parts.is_absolute() or '..' in parts.parts or '\\' in item.filename:
+                    raise ValueError('unsafe cell.json archive path')
+                if item.file_size > MAX_CELL_BYTES:
+                    raise ValueError('cell.json exceeds size limit')
+                candidates.append(item)
+            if len(candidates) != 1:
+                raise ValueError('archive must contain exactly one cell.json')
+            raw = archive.read(candidates[0])
+    else:
+        if path.stat().st_size > MAX_CELL_BYTES:
+            raise ValueError('cell.json exceeds size limit')
+        raw = path.read_bytes()
+    value = json.loads(raw.decode('utf-8'))
+    if not isinstance(value, dict):
+        raise ValueError('cell.json must contain an object')
+    return value
+
+
+def save_cell(cell: dict, path: str | Path, *, overwrite: bool = False) -> Path:
+    check = validate_cell(cell)
+    if not check['valid']:
+        raise ValueError('invalid Cell: ' + '; '.join(check['errors']))
+    path = Path(path)
+    mode = 'w' if overwrite else 'x'
+    with path.open(mode, encoding='utf-8') as stream:
+        json.dump(cell, stream, indent=2, ensure_ascii=False, allow_nan=False)
+        stream.write('\n')
+    return path
+
+
+def validate_cell(cell: Any) -> dict:
+    """Validate either supported local Cell family; malformed data fails closed."""
+    base = dict(valid=False, errors=[], schemaFamily=None, schemaVersion=None,
+                cellId=None, objectCount=0, bounds=None, stage=None, notCanon=None)
+    if not isinstance(cell, dict):
+        base['errors'] = ['Cell must be an object']
+        return base
+    errors: list[str] = []
+    v1 = cell.get('schema') == 'clayspace.cell.local-fragment' and cell.get('schemaVersion') == '1.0.0'
+    legacy = cell.get('schemaVersion') == '0.1'
+    if not (v1 or legacy):
+        base.update(schemaFamily=cell.get('schema'), schemaVersion=cell.get('schemaVersion'),
+                    errors=['unsupported Cell format'])
+        return base
+    identity = _object(cell.get('identity'))
+    cell_id = identity.get('cellId') if v1 else cell.get('id')
+    if not _text(cell_id):
+        errors.append('Cell ID must be a non-empty string')
+
+    # A Cell is local. Workflow metadata may exist for a host project, but a
+    # baked master-world transform is never part of the portable source Cell.
+    if not _absent(cell.get('placement')):
+        errors.append('source Cell must remain locally unplaced')
+    for field in ('worldTransform', 'masterWorldCoordinates'):
+        if cell.get(field) is not None:
+            errors.append(f'source Cell must not contain {field}')
+    for container in ('portability', 'handoff'):
+        value = cell.get(container)
+        if value is not None and not isinstance(value, dict):
+            errors.append(f'{container} must be an object')
+        flags = _object(value)
+        if not _absent(flags.get('placement')):
+            errors.append(f'{container}.placement must remain none')
+        if flags.get('containsWorldTransform') is True:
+            errors.append(f'{container} declares a world transform')
+        if flags.get('masterWorldCoordinates') not in (None, False):
+            errors.append(f'{container} declares master-world coordinates')
+
+    if v1:
+        cs = _object(cell.get('coordinateSystem'))
+        axes = cs.get('axes')
+        if not isinstance(axes, str) or not all(t in axes.lower() for t in ('x-right', 'y-up', 'z-forward')):
+            errors.append('axes must describe x-right / y-up / z-forward')
+        origin, units = cs.get('localOrigin'), cs.get('units')
+    else:
+        cs = cell.get('coordinateSystem')
+        if cs != 'x-right-y-up-z-forward-meters':
+            errors.append('unsupported coordinateSystem')
+        origin, units = cell.get('origin'), cell.get('units')
+    if not _vector(origin) or any(x != 0 for x in origin):
+        errors.append('local origin must be [0,0,0]')
+    if units != 'meters':
+        errors.append('units must be meters')
+
+    geometry = cell.get('geometry' if v1 else 'objects')
+    if not isinstance(geometry, list) or not geometry:
+        errors.append('Cell geometry must be a non-empty array')
+        geometry = []
+    ids = set()
+    for index, item in enumerate(geometry):
+        label = f'geometry[{index}]'
+        if not isinstance(item, dict):
+            errors.append(f'{label} must be an object')
+            continue
+        item_id = item.get('id')
+        if not _text(item_id):
+            errors.append(f'{label} requires a string ID')
+        elif item_id in ids:
+            errors.append(f'duplicate geometry ID {item_id}')
+        else:
+            ids.add(item_id)
+        if v1:
+            primitive = item.get('primitive')
+            if primitive not in ('box', 'prism', 'cylinder', 'sphere', 'plane'):
+                errors.append(f'{label} unsupported primitive')
+            if not _vector(item.get('position')):
+                errors.append(f'{label} invalid position')
+            if not _vector(item.get('rotationDeg', [0, 0, 0])):
+                errors.append(f'{label} invalid rotationDeg')
+            scale = item.get('scale', [1, 1, 1])
+            if not _vector(scale) or any(v <= 0 for v in scale):
+                errors.append(f'{label} invalid scale')
+            if primitive == 'box':
+                size = item.get('size')
+                if not _vector(size) or any(v <= 0 for v in size):
+                    errors.append(f'{label} invalid size')
+            elif primitive == 'prism':
+                footprint = item.get('footprintXZ')
+                if not isinstance(footprint, list) or len(footprint) < 3 or not all(_vector(p, 2) for p in footprint):
+                    errors.append(f'{label} invalid footprintXZ')
+                y0, y1 = item.get('y0'), item.get('y1')
+                if not _finite(y0) or not _finite(y1) or y1 <= y0:
+                    errors.append(f'{label} invalid prism height')
+            elif primitive == 'cylinder':
+                if not _finite(item.get('radius')) or item.get('radius', 0) <= 0:
+                    errors.append(f'{label} invalid radius')
+                if not _finite(item.get('height')) or item.get('height', 0) <= 0:
+                    errors.append(f'{label} invalid height')
+                if 'segments' in item and (not isinstance(item['segments'], int) or item['segments'] < 3 or item['segments'] > 256):
+                    errors.append(f'{label} segments must be an integer from 3 to 256')
+            elif primitive == 'sphere':
+                if not _finite(item.get('radius')) or item.get('radius', 0) <= 0:
+                    errors.append(f'{label} invalid radius')
+            elif primitive == 'plane':
+                size = item.get('size')
+                if not _vector(size, 2) or any(v <= 0 for v in size):
+                    errors.append(f'{label} invalid plane size')
+        else:
+            if item.get('kind') not in ('box', 'card', 'road-strip'):
+                errors.append(f'{label} unsupported kind')
+            g = _object(item.get('geometry'))
+            if not all(_finite(g.get(k)) for k in ('x','y','z')):
+                errors.append(f'{label} invalid xyz')
+            if not all(_finite(g.get(k)) and g[k] > 0 for k in ('w','h','d')):
+                errors.append(f'{label} invalid dimensions')
+            for field in ('yaw','pitch','roll'):
+                if field in g and not _finite(g[field]):
+                    errors.append(f'{label} invalid {field}')
+
+    if v1 and 'bounds' in cell and cell.get('bounds') is not None and not isinstance(cell.get('bounds'), dict):
+        errors.append('bounds must be an object')
+    aabb = _object(cell.get('bounds')).get('aabb') if v1 else None
+    if v1 and aabb is not None:
+        b = _object(aabb)
+        if not _vector(b.get('min')) or not _vector(b.get('max')):
+            errors.append('bounds.aabb requires finite min/max vectors')
+        elif any(hi <= lo for lo, hi in zip(b['min'], b['max'])):
+            errors.append('bounds.aabb must have positive dimensions')
+
+    base.update(valid=not errors, errors=errors,
+                schemaFamily='clayspace.cell.local-fragment' if v1 else 'clayspace-cell',
+                schemaVersion=cell.get('schemaVersion'), cellId=cell_id,
+                objectCount=len(geometry), bounds=deepcopy(aabb),
+                stage=cell.get('stage'), notCanon=cell.get('notCanon'))
+    return base
+
+
+def inspect_cell(cell: dict) -> dict:
+    result = validate_cell(cell)
+    return {**result, 'placementStatus': 'local' if result['valid'] else None}
+
+
+def new_box_cell(*, cell_id: str, name: str, size=(2.0, 2.0, 2.0)) -> dict:
+    """Create a generic ground-centred editable local Cell scaffold."""
+    if not _text(cell_id) or not _text(name) or not _vector(size) or any(v <= 0 for v in size):
+        raise ValueError('Cell needs a non-empty ID/name and three positive dimensions')
+    w, h, d = size
+    return {
+        'schema': 'clayspace.cell.local-fragment', 'schemaVersion': '1.0.0',
+        'identity': {'cellId': cell_id, 'title': name},
+        'coordinateSystem': {'axes': 'x-right / y-up / z-forward', 'units': 'meters', 'localOrigin': [0,0,0]},
+        'bounds': {'aabb': {'min': [-w/2,0,-d/2], 'max': [w/2,h,d/2]}},
+        'geometry': [{'id': 'MASS-001', 'primitive': 'box', 'position': [0,h/2,0], 'size': [w,h,d], 'rotationDeg': [0,0,0], 'scale': [1,1,1]}],
+        'portability': {'containsWorldTransform': False, 'placement': 'none'}
+    }

clayspace-0.1.1/clayspace/cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+import argparse, json
+from pathlib import Path
+from .cell import inspect_cell, load_cell, new_box_cell, save_cell, validate_cell
+from .model import add_box, add_cylinder, add_sphere, move_geometry, remove_geometry
+from .placement import make_placement
+from .preview import preview_cell, preview_world
+from .resources import manifest, schema
+from .world import inspect_world_snapshot, load_world_snapshot, new_world, place_cell, save_world_snapshot, validate_world_snapshot
+
+
+def _print(obj): print(json.dumps(obj,indent=2,ensure_ascii=False))
+def _vec(text,n=3):
+    parts=[p.strip() for p in text.split(',')]
+    if len(parts)!=n: raise argparse.ArgumentTypeError(f'expected {n} comma-separated numbers')
+    try:return [float(p) for p in parts]
+    except ValueError as exc: raise argparse.ArgumentTypeError('values must be numbers') from exc
+
+def _vec3(text): return _vec(text,3)
+def _write_cell(cell,path,force): save_cell(cell,path,overwrite=force)
+def _write_world(world,path,force): save_world_snapshot(world,path,overwrite=force)
+
+
+def main(argv=None):
+    parser=argparse.ArgumentParser(prog='clayspace',description='Standalone local spatial modeling toolkit')
+    sub=parser.add_subparsers(dest='cmd',required=True)
+    sub.add_parser('about')
+    ps=sub.add_parser('schema');ps.add_argument('name',choices=['cell','placement','world'])
+
+    pc=sub.add_parser('cell');cs=pc.add_subparsers(dest='cell_cmd',required=True)
+    p=cs.add_parser('init');p.add_argument('--id',required=True);p.add_argument('--name',required=True);p.add_argument('--size',type=_vec3,default=[2,2,2]);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    for name in ('validate','inspect'):
+        p=cs.add_parser(name);p.add_argument('path')
+    p=cs.add_parser('add-box');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--position',type=_vec3,default=[0,0,0]);p.add_argument('--size',type=_vec3,required=True);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('add-cylinder');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--position',type=_vec3,default=[0,0,0]);p.add_argument('--radius',type=float,required=True);p.add_argument('--height',type=float,required=True);p.add_argument('--segments',type=int,default=24);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('add-sphere');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--position',type=_vec3,default=[0,0,0]);p.add_argument('--radius',type=float,required=True);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('move');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--position',type=_vec3,required=True);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('remove');p.add_argument('path');p.add_argument('--id',required=True);p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=cs.add_parser('preview');p.add_argument('path');p.add_argument('--out',required=True)
+
+    pp=sub.add_parser('placement');pps=pp.add_subparsers(dest='placement_cmd',required=True)
+    p=pps.add_parser('make');p.add_argument('cell_path');p.add_argument('--position',required=True,type=_vec3);p.add_argument('--yaw-radians',type=float,default=0);p.add_argument('--scale',type=float,default=1);p.add_argument('--id');p.add_argument('--out')
+
+    pw=sub.add_parser('world');ws=pw.add_subparsers(dest='world_cmd',required=True)
+    p=ws.add_parser('init');p.add_argument('--id',required=True);p.add_argument('--name');p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    p=ws.add_parser('place');p.add_argument('world_path');p.add_argument('--cell',required=True);p.add_argument('--entity-id',required=True);p.add_argument('--position',type=_vec3,required=True);p.add_argument('--yaw-radians',type=float,default=0);p.add_argument('--scale',type=float,default=1);p.add_argument('--name');p.add_argument('--out',required=True);p.add_argument('--force',action='store_true')
+    for name in ('validate','inspect'):
+        p=ws.add_parser(name);p.add_argument('path')
+    p=ws.add_parser('preview');p.add_argument('path');p.add_argument('--out',required=True)
+
+    args=parser.parse_args(argv)
+    if args.cmd=='about':_print(manifest());return 0
+    if args.cmd=='schema':_print(schema(args.name));return 0
+    if args.cmd=='cell':
+        if args.cell_cmd=='init':
+            _write_cell(new_box_cell(cell_id=args.id,name=args.name,size=args.size),args.out,args.force);return 0
+        cell=load_cell(args.path)
+        if args.cell_cmd=='validate':
+            r=validate_cell(cell);_print(r);return 0 if r['valid'] else 1
+        if args.cell_cmd=='inspect':
+            r=inspect_cell(cell);_print(r);return 0 if r['valid'] else 1
+        if args.cell_cmd=='add-box':out=add_box(cell,object_id=args.id,position=args.position,size=args.size)
+        elif args.cell_cmd=='add-cylinder':out=add_cylinder(cell,object_id=args.id,position=args.position,radius=args.radius,height=args.height,segments=args.segments)
+        elif args.cell_cmd=='add-sphere':out=add_sphere(cell,object_id=args.id,position=args.position,radius=args.radius)
+        elif args.cell_cmd=='move':out=move_geometry(cell,object_id=args.id,position=args.position)
+        elif args.cell_cmd=='remove':out=remove_geometry(cell,object_id=args.id)
+        elif args.cell_cmd=='preview':preview_cell(cell,args.out);return 0
+        else:return 2
+        _write_cell(out,args.out,args.force);return 0
+    if args.cmd=='placement' and args.placement_cmd=='make':
+        obj=make_placement(load_cell(args.cell_path),position=args.position,yaw_radians=args.yaw_radians,scale=args.scale,placement_id=args.id)
+        text=json.dumps(obj,indent=2,ensure_ascii=False)+'\n'
+        Path(args.out).write_text(text,encoding='utf-8') if args.out else print(text,end='')
+        return 0
+    if args.cmd=='world':
+        if args.world_cmd=='init':_write_world(new_world(world_id=args.id,label=args.name),args.out,args.force);return 0
+        world=load_world_snapshot(args.world_path if hasattr(args,'world_path') else args.path)
+        if args.world_cmd=='place':
+            out=place_cell(world,load_cell(args.cell),entity_id=args.entity_id,position=args.position,yaw_radians=args.yaw_radians,scale=args.scale,display_name=args.name)
+            _write_world(out,args.out,args.force);return 0
+        if args.world_cmd=='validate':r=validate_world_snapshot(world);_print(r);return 0 if r['valid'] else 1
+        if args.world_cmd=='inspect':r=inspect_world_snapshot(world);_print(r);return 0 if r['valid'] else 1
+        if args.world_cmd=='preview':preview_world(world,args.out);return 0
+    return 2
+
+if __name__=='__main__':raise SystemExit(main())