jbmui

SceneGeometry

  • Foundations

Shared points, bounds, arc-length path interpolation and travel tilt.

Install

npx shadcn@latest add @jbm/scene-geometry

Needs the @jbm entry in components.json; see Install once.

Usage

Place and tilt an object along a path
import { pointOn, pathTilt } from "@/jbm/lib/geometry"const path = [{ x: 40, y: 170 }, { x: 220, y: 50 }, { x: 460, y: 130 }]const at = pointOn(path, 0.5)const angle = pathTilt(path, 0.5)<g transform={`translate(${at.x} ${at.y}) rotate(${angle})`} />

API

Stage
n/a

Geometry helpers only; nothing renders. The gallery draws an example path to illustrate the points.

unitfunction

Clamps a progress value to 0–1, treating non-finite input as 0.

ParamTypeDefaultDescription
valuenumberrequiredAny number, usually a progress value.

Returns The value clamped to 0–1, or 0 when it is NaN or infinite.

pointOnfunction

Point at a fraction of a polyline's total length (arc-length, not per segment). Repeated points and a one-point path are valid; an empty path throws.

ParamTypeDefaultDescription
pathreadonly Pt[]requiredPolyline points in the caller's coordinate space; at least one.
progressnumberrequired0–1 fraction of the total length; clamped with unit.

Returns A new { x, y } on the path; the last point at 1 or when the path has no length.

pathTiltfunction

Restrained travel tilt from the direction of travel around a progress point (sampled ±0.01), measured against horizontal regardless of left/right direction.

ParamTypeDefaultDescription
pathreadonly Pt[]requiredPolyline points, as for pointOn.
progressnumberrequired0–1 fraction of the total length.

Returns Degrees clamped to −18…18; positive when the path descends on screen (y grows).

Pttype

A point { x, y } in scene (SVG user) units.

Boxtype

A Pt plus w and h: the top-left corner and size of a rectangle.

QA checks

  • pointOn at 0, 0.5, and 1 returns the first point, the arc-length midpoint, and the last point; out-of-range progress clamps.
  • A path with repeated points or a single point never returns NaN.
  • pathTilt stays within ±18° on steep segments; objects moving right-to-left tilt the same way as left-to-right on the same slope.