Core Types

All types are exported from @polycss/react, @polycss/vue, and @polycss/core.

Polygon

The atomic renderable primitive. Each polygon becomes one atlas-backed <i> DOM element for textured and flat-color faces.

interface Polygon {
  /** Three or more [x, y, z] world-space points, CCW winding from the outside. */
  vertices: [number, number, number][];
  /** CSS color. Falls back to "#cccccc" when neither color nor texture is set. */
  color?: string;
  /** Image URL for UV-mapped rendering. When set with `uvs`, the renderer
   *  applies an affine UV transform. Without `uvs`, single-tile fill. */
  texture?: string;
  /** UV coordinates — one per vertex. Must match vertices.length.
   *  Mismatched arrays are stripped during normalizePolygons(). */
  uvs?: [number, number][];
  /** User-controlled metadata. Reflected to the DOM as data-* attributes
   *  when rendering via <Poly>. Keys must have string, number, or boolean values. */
  data?: Record<string, string | number | boolean>;
}

---

DirectionalLight

Controls directional and ambient lighting for the scene.

interface DirectionalLight {
  /** Direction the light shines toward (normalized). */
  direction: [number, number, number];
  /** Directional light color hex (default: "#ffffff"). */
  color?: string;
  /** Ambient light intensity 0–1 (default: 0.4). */
  ambient?: number;
  /** Ambient light tint hex (default: "#ffffff"). */
  ambientColor?: string;
}

---

Vec2

A 2D point or UV coordinate.

type Vec2 = [number, number];

---

Vec3

A 3D point or direction.

type Vec3 = [number, number, number];

---

ParseResult

Unified return shape from all mesh parsers (parseObj, parseGltf, loadMesh).

interface ParseResult {
  /** Parsed and validated polygon array, ready for rendering. */
  polygons: Polygon[];
  /** Blob URLs minted during parse (e.g. embedded GLB textures).
   *  Revoked when dispose() is called. */
  objectUrls: string[];
  /** Revoke all objectUrls. Idempotent. Safe to call on unmount. */
  dispose: () => void;
  /** Non-fatal warnings raised during parse (dropped polygons, UV mismatches, etc.). */
  warnings: string[];
  /** Optional format-specific metadata. */
  metadata?: {
    triangleCount?: number;
    meshes?: string[];
    materials?: string[];
    sourceBytes?: number;
  };
}

---

NormalizeResult

Return type of normalizePolygons.

interface NormalizeResult {
  polygons: Polygon[];
  warnings: string[];
}

---

ObjParseOptions

Options for parseObj.

interface ObjParseOptions {
  /** Scale the model so its longest axis is this many world units. */
  targetSize?: number;
  /** Shift all vertices by this amount after scaling. */
  gridShift?: number;
  /** Fallback color for un-colored faces (default: "#cccccc"). */
  defaultColor?: string;
  /** Override per-material colors (material name → CSS color). */
  materialColors?: Record<string, string>;
  /** Override per-material textures (material name → image URL). */
  materialTextures?: Record<string, string>;
  /** Only include these named OBJ objects. */
  includeObjects?: string[];
  /** Exclude these named OBJ objects. */
  excludeObjects?: string[];
  /** Quantize vertex colors to this palette. */
  palette?: string[];
}

---

GltfParseOptions

Options for parseGltf.

interface GltfParseOptions {
  /** Scale the model so its longest axis is this many world units. */
  targetSize?: number;
  /** Shift all vertices by this amount after scaling. */
  gridShift?: number;
  /** Fallback color for un-colored faces. */
  defaultColor?: string;
  /** Override per-material colors. */
  materialColors?: Record<string, string>;
  /** Treat the model's up axis as Y or Z. Most GLB files use Y. */
  upAxis?: "y" | "z";
  /** Base URL for resolving external texture references in .gltf files. */
  baseUrl?: string;
  /** Custom buffer resolver for external .bin files. */
  resolveBuffer?: (uri: string) => Promise<Uint8Array> | Uint8Array;
}

---

MtlParseResult

Return type of parseMtl.

interface MtlParseResult {
  /** Material name → CSS color. */
  colors: Record<string, string>;
  /** Material name → texture image path. */
  textures: Record<string, string>;
}

---

AutoRotateOption

Configures automatic camera rotation.

type AutoRotateOption =
  | boolean          // true = default Y-axis at speed 0.3, pauseOnInteraction
  | number           // speed in degrees/frame on Y axis
  | {
      axis?: "x" | "y";
      speed?: number;
      pauseOnInteraction?: boolean;
    };

CameraState

Internal camera state (used by createIsometricCamera).

interface CameraState {
  rotX: number;
  rotY: number;
  zoom: number;
  pan: number;
  tilt: number;
  perspective: number | null;  // null = parallel projection
  invertMultiplier: 1 | -1;
  depthOffset: number;
  invert?: boolean;
}