@layoutit/polycss-core 0.2.0 → 0.2.1

package/README.md

@@ -1,135 +1,199 @@
-> **Status: pre-1.0. APIs may still change before a stable 1.0 release.**
+# PolyCSS
 
-# @layoutit/polycss-core
+A CSS polygon mesh library. A 3D engine for the DOM. Renders OBJ/MTL, GLB and VOX as real HTML elements transformed with CSS `matrix3d(...)`. Supports colors, textures, lighting, shadows, shapes and animations. Works with React, Vue or plain JavaScript.
 
-Framework-agnostic math, parsers, and helpers for CSS polygon-mesh rendering. Zero browser globals: runs in Node, workers, or any JS environment.
+Visit [polycss.com](https://polycss.com) for docs and model examples.
 
-This package contains the entire non-rendering side of polycss: OBJ / glTF / GLB / MagicaVoxel parsers, polygon normalization, coplanar merge, Lambert lighting, isometric camera state, and all shared TypeScript types.
+<img width="1600" height="300" alt="PolyCSS primitives banner" src="https://github.com/user-attachments/assets/b05e2204-9323-4f83-8d1b-01ea0dd000db" />
 
-## When to use directly
+## Installation
 
-Most users install `@layoutit/polycss-react`, `@layoutit/polycss-vue`, or `@layoutit/polycss` (vanilla). Those packages include `@layoutit/polycss-core` as a transitive runtime dependency and re-export its public types and functions, so you never need to write `import ... from "@layoutit/polycss-core"` in application code.
+```bash
 
-Install `@layoutit/polycss-core` directly when you:
+# Vanilla
+npm install @layoutit/polycss
 
-- Build custom rendering outside React / Vue / vanilla (e.g., a Svelte wrapper, a server-side OBJ validator, a CLI mesh processor).
-- Want only the parsers / math without any rendering layer.
-- Are writing a polycss plugin or tooling that must remain framework-neutral.
+# React
+npm install @layoutit/polycss-react
+
+# Vue
+npm install @layoutit/polycss-vue
 
-```bash
-npm install @layoutit/polycss-core
 ```
 
-## Public surface
 
-### Types
+You can also load PolyCSS directly from a CDN. Here is a minimal custom-element scene:
 
-| Type | Description |
-|---|---|
-| `Vec2` | `[number, number]`: 2D point or UV coordinate |
-| `Vec3` | `[number, number, number]`: 3D point or direction |
-| `Polygon` | Single renderable polygon: `vertices`, optional `color`, `texture`, `uvs`, `data` |
-| `PolyDirectionalLight` | Directional light: `direction`, optional `color`, optional `intensity` |
-| `PolyAmbientLight` | Ambient fill light: optional `color`, optional `intensity` |
-| `ParseResult` | Unified parser return: `polygons`, `objectUrls`, `dispose()`, `warnings` |
-| `ObjParseOptions` | Options for `parseObj` |
-| `GltfParseOptions` | Options for `parseGltf` |
-| `VoxParseOptions` | Options for `parseVox` |
-| `MtlParseResult` | `{ colors, textures }` from `parseMtl` |
-| `NormalizeResult` | `{ polygons, warnings }` from `normalizePolygons` |
-| `CameraState` | Camera target, angles, zoom, and dolly distance |
-| `CameraHandle` | Mutable camera object from `createIsometricCamera` |
-| `AutoRotateOption` | `boolean | number | { axis, speed, pauseOnInteraction }` |
-| `BoxPolygonsOptions` | Options for `boxPolygons`: size/center or min/max bounds, materials, face overrides |
-
-### Functions
-
-| Function | Description |
-|---|---|
-| `normalizePolygons(input)` | Validates polygons. Drops degenerate ones, auto-triangulates non-coplanar N-gons, strips mismatched UVs. Returns `{ polygons, warnings }`. |
-| `mergePolygons(polygons)` | Coplanar same-material adjacent merge. Reduces DOM element count on flat surfaces. |
-| `optimizeMeshPolygons(polygons, options?)` | Applies lossless or lossy mesh-resolution optimization and chooses the smallest accepted candidate; defaults to `meshResolution: "lossy"`. |
-| `computeSceneBbox(polygons)` | Computes min/max bounds across all polygon vertices. |
-| `createIsometricCamera(initial?)` | Creates a mutable camera handle with `state`, `update(partial)`, and `getStyle()`. |
-| `boxPolygons(options?)` | Creates six quad `Polygon`s for an axis-aligned box/cuboid. Supports per-face material/data overrides and omitted faces. |
-| `parseObj(text, options?)` | Parses OBJ text into `ParseResult`. Supports UV (`vt`), materials, `map_Kd` textures. |
-| `parseMtl(text)` | Parses MTL text into `{ colors, textures }`. |
-| `parseGltf(buffer, options?)` | Parses GLB or glTF `ArrayBuffer` into `ParseResult`. Extracts embedded textures as blob URLs. |
-| `parseVox(buffer, options?)` | Parses MagicaVoxel `.vox` `ArrayBuffer` into `ParseResult`. Face-culls interior voxel faces and emits exposed quads. `targetSize` snaps to integer voxel CSS cells for the fast-path renderer. |
-| `loadMesh(url, options?)` | Fetches a URL, dispatches to the right parser by extension (`.obj`, `.glb`, `.gltf`, `.vox`). Returns `Promise<ParseResult>` and defaults to `meshResolution: "lossy"`. |
-| `parseColor(input)` | Parse any CSS color string to `{ r, g, b, a }`. |
-| `shadeColor(input, lambert, ...)` | Apply Lambert shading factor to a color. |
-| `computeShapeLighting(normal, baseColor, light?)` | Compute shaded color for a polygon face given a directional light and surface normal. |
-
-## Examples
-
-### Parse an OBJ file
+```html
+<script type="module" src="https://esm.sh/@layoutit/polycss/elements"></script>
 
-```ts
-import { parseObj } from "@layoutit/polycss-core";
+<poly-camera rot-x="65" rot-y="45">
+  <poly-scene>
+    <poly-orbit-controls drag wheel></poly-orbit-controls>
+    <poly-box size="100" color="#ffd166"></poly-box>
+  </poly-scene>
+</poly-camera>
+```
 
-const text = await fetch("/cottage.obj").then(r => r.text());
-const { polygons, warnings, dispose } = parseObj(text, {
-  targetSize: 40,
-  defaultColor: "#cccccc",
-});
+<img width="2500" height="1145" alt="PolyCSS intro" src="https://github.com/user-attachments/assets/0e5df0d8-04a8-4e50-8e3a-1097a96ce42f" />
+
+## Framework Components
 
-console.log(polygons.length, "polygons");
-warnings.forEach(w => console.warn(w));
+React and Vue expose the same component model. `<PolyCamera>` owns the viewpoint, `<PolyScene>` owns lighting and atlas options, and `<PolyMesh>` loads or receives polygon data.
 
-// Revoke any blob URLs created during parse (OBJ rarely creates them,
-// but always call dispose() for correctness):
-dispose();
+```tsx
+import { PolyCamera, PolyScene, PolyOrbitControls, PolyMesh } from "@layoutit/polycss-react";
+
+export default function App() {
+  return (
+    <PolyCamera rotX={65} rotY={45}>
+      <PolyScene textureLighting="dynamic">
+        <PolyOrbitControls drag wheel />
+        <PolyMesh src="/gallery/obj/cottage.obj" mtl="/gallery/obj/cottage.mtl" />
+      </PolyScene>
+    </PolyCamera>
+  );
+}
 ```
 
-### Normalize a polygon list
+## API Reference
 
-```ts
-import { normalizePolygons } from "@layoutit/polycss-core";
-import type { Polygon } from "@layoutit/polycss-core";
+### PolyCamera
 
-const raw: Polygon[] = [
-  { vertices: [[0,0,0], [1,0,0], [0,1,0]], color: "#f00" },
-  { vertices: [[0,0,0], [0,0,0], [0,0,0]] }, // degenerate: will be dropped
-  { vertices: [[0,0,0], [1,0,0], [0.5,1,0], [0.5,1,0.1]] }, // non-coplanar quad → triangulated
-];
+- `rotX`, `rotY` control the orbit angle in degrees.
+- `zoom` scales the projected scene.
+- `target` pans the camera target in world coordinates.
+- `distance` adds dolly pull-back.
+- `PolyCamera` is the orthographic default. Use `PolyPerspectiveCamera` when you want perspective depth.
 
-const { polygons, warnings } = normalizePolygons(raw);
-console.log(polygons.length); // 2 (degenerate dropped; quad fan-triangulated into 2)
-warnings.forEach(w => console.warn(w));
-```
+### PolyScene
 
-### Merge coplanar polygons
+- `polygons` renders a static `Polygon[]` directly.
+- `directionalLight` and `ambientLight` control scene lighting.
+- `textureLighting` chooses `"baked"` or `"dynamic"`.
+- `textureQuality` controls atlas raster budget.
+- Solid seam bleed is automatic on detected shared solid edges.
+- `strategies` can disable selected render strategies for diagnostics.
+- `autoCenter` rotates around the rendered mesh bounds instead of world origin.
 
-```ts
-import { parseGltf, mergePolygons } from "@layoutit/polycss-core";
+### PolyMesh
 
-const buf = await fetch("/cottage.glb").then(r => r.arrayBuffer());
-const { polygons, dispose } = parseGltf(buf, { targetSize: 60 });
+- `src` loads `.obj`, `.gltf`, `.glb`, or `.vox` files.
+- `mtl` loads companion OBJ materials.
+- `polygons` accepts pre-parsed geometry.
+- `position`, `scale`, and `rotation` transform the mesh wrapper.
+- `autoCenter` shifts the mesh bbox center to local origin.
+- `meshResolution` chooses `"lossy"` (default) or `"lossless"` optimization.
+- `castShadow` emits CSS-projected shadows in dynamic lighting mode.
 
-// Merge coplanar same-material triangles to reduce DOM element count
-const merged = mergePolygons(polygons);
-console.log(`${polygons.length} triangles → ${merged.length} merged polygons`);
+### Controls
 
-dispose(); // always revoke GLB blob URLs when done
-```
+- `<PolyOrbitControls>` adds drag orbit, shift-drag pan, wheel zoom, and optional auto-rotate.
+- `<PolyMapControls>` uses pan-first map-style input.
+- `<PolyFirstPersonControls>` provides keyboard and pointer-look navigation.
+- `<PolyTransformControls>` adds translate/rotate gizmos for selected mesh handles.
 
-### Create a box shape
+### Polygon Data Model
+
+Each polygon describes one renderable face:
 
 ```ts
-import { boxPolygons } from "@layoutit/polycss-core";
-
-const polygons = boxPolygons({
-  min: [0, 0, 0],
-  max: [2, 1, 0.5],
-  color: "#d8d2c7",
-  data: { tileId: "tile-1" },
-  faces: {
-    top: {
-      texture: "/tile.png",
-      data: { face: "top" },
-    },
-    bottom: false,
+const polygons = [
+  {
+    vertices: [[0, 0, 0], [60, 0, 0], [0, 60, 0]],
+    color: "#f97316",
+  },
+  {
+    vertices: [[0, 0, 0], [60, 0, 0], [60, 60, 0], [0, 60, 0]],
+    texture: "/texture.png",
+    uvs: [[0, 0], [1, 0], [1, 1], [0, 1]],
   },
+];
+```
+
+Render polygons directly when you need per-face DOM events or custom styling:
+
+```tsx
+<PolyCamera>
+  <PolyScene>
+    {polygons.map((polygon, index) => (
+      <Poly
+        key={index}
+        {...polygon}
+        onClick={() => console.log("clicked polygon", index)}
+        className="my-polygon"
+      />
+    ))}
+  </PolyScene>
+</PolyCamera>
+```
+
+## Loading Mesh Files
+
+Use `loadMesh()` to parse supported model formats:
+
+```ts
+import { createPolyCamera, createPolyScene, loadMesh } from "@layoutit/polycss";
+
+const host = document.getElementById("polycss")!;
+const camera = createPolyCamera({ rotX: 65, rotY: 45 });
+const scene = createPolyScene(host, { camera });
+
+const mesh = await loadMesh("https://polycss.com/gallery/obj/cottage.obj", {
+  mtlUrl: "https://polycss.com/gallery/obj/cottage.mtl",
 });
+
+scene.add(mesh);
 ```
+
+Supported formats:
+
+- OBJ + MTL, including `map_Kd` textures and UV coordinates.
+- glTF / GLB, including embedded images and `TEXCOORD_0`.
+- MagicaVoxel `.vox`, with direct voxel fast paths when eligible.
+- Generated primitives: box, plane, ring, sphere, torus, cylinder, cone, and Platonic solids.
+
+## Performance
+
+PolyCSS renders in the DOM, so performance is mostly determined by how many polygons are mounted and how much texture atlas area they consume. The renderer uses several CSS strategies so simple surfaces stay cheap and textured or irregular surfaces fall back to atlas slices.
+
+- One visible polygon becomes one leaf DOM element.
+- Flat rectangles and stable quads use solid CSS leaves.
+- Textured polygons are packed into generated texture atlases.
+- Dynamic lighting runs through CSS custom properties instead of per-frame JavaScript.
+- Voxel-shaped meshes mount only camera-facing leaves when the mesh is eligible.
+- `meshResolution: "lossy"` merges compatible polygons, then may spend a small split budget to repair high-risk seams.
+
+Renderer internals:
+
+Each visible polygon is emitted as one leaf element; the renderer chooses the least expensive CSS primitive that can represent the polygon, then uses `matrix3d(...)` to place that primitive in 3D space.
+
+- `<b>` uses `background: currentColor` on a fixed box for solid rectangles and stable quads.
+- `<u>` uses `corner-shape` for stable triangles and beveled-corner solids, with a `border-width` triangle fallback when needed.
+- `<i>` clips solid polygons with `border-shape: polygon(...)` when the browser supports it.
+- `<s>` maps a packed texture-atlas slice with `background-image`, and is the fallback for textured or unsupported shapes.
+
+## Packages
+
+| Package | Description |
+|---|---|
+| `@layoutit/polycss-core` | Pure math, parsers, lighting, camera helpers, mesh optimization. Zero browser globals. |
+| `@layoutit/polycss` | Vanilla custom elements and imperative `createPolyScene` API. |
+| `@layoutit/polycss-react` | React components, hooks, controls, and core re-exports. |
+| `@layoutit/polycss-vue` | Vue 3 components, composables, controls, and core re-exports. |
+
+## Made with PolyCSS
+
+[Layoutit Voxels](https://voxels.layoutit.com)
+-> A CSS Voxel editor
+
+<img width="1000" height="600" alt="layoutit-voxels" src="https://polycss.com/layoutit-voxels.png" />
+
+[Layoutit Terra](https://terra.layoutit.com)
+-> A CSS Terrain Generator
+
+<img width="1000" height="601" alt="layoutit-terra" src="https://polycss.com/layoutit-terra.png" />
+
+## License
+
+MIT.