Guides

Guides

Task-oriented walkthroughs. Every example below is a runnable, commented script in examples/, exercised by the test suite so it never drifts from the API.

Learning path

Work top to bottom — each builds on the last.

#	Script	The idea it teaches
01	quickstart	construct → compose → resolve; scalars flowing across types
02	coordinate_frames	a kinematic chain; grounding, and why an unplaced frame is Unresolvable
03	decidability_and_partiality	value-dependent partialities, reasons, propagation; predicates as Bool
04	visualizing_resolvers	render the lazy graph to see where an unresolvability lives
05	time_and_clocks	durations, instants, intervals & coverage with gaps
06	signals_over_time	signals as partial functions of time; resample/reparameterize; slerp
07	aligning_and_warping	recover the time map between two recordings from landmarks
08	point_clouds_over_time	a marker cloud over time — an occluded marker is honestly Unresolvable
09	regions_and_patches	the 2D region algebra, the balance margin, and a bounded-patch Face
10	contact_over_time	the contact spine end-to-end; touchdown & release from marker data

python examples/01_quickstart.py

Signals over time

A signal reconstructs a value from samples and is honest about gaps — sampling across a dropout is Unresolvable, not interpolated fiction. Build with from_samples/sampled (with max_gap= to mark dropouts, via=/outside= for kernel/boundary), then at, resample, reparameterize (by a TimeMap or monotonic TimeWarp), restrict, and derivatives (velocity, angular_velocity). The lift/map escape hatch combines any sources per instant. Start with example 06; deep design in docs/time.md.

Marker clouds (collections)

A Point3Bundle is a keyed, occlusion-aware set; a Point3BundleSignal is one over time. at(t) gives the cloud at an instant, key(k) gives one marker's gappy trajectory, and the two agree on the support (the commuting square). Folds (centroid), broadcasts, and key-aligned composition all flow partiality. Start with example 08; deep design in docs/collections.md.

Regions & contact

Build a support polygon with Region2.hull(markers), read the balance margin off its positive-inside signed_distance, and compose patches with the general boolean algebra. Lift a region onto a Plane to get a Face — the bounded patch whose clearance clamps into the footprint. Over time, the contact spine is:

clearances = ground_cloud.fit_plane().signed_distance(foot_cloud)  # ScalarBundleSignal
contact = clearances.min().le(0.0)                                 # BoolSignal
contact.when_true().resolve()    # contact interval(s)
contact.first_true().resolve()   # touchdown
contact.last_true().resolve()    # release

Start with examples 09 and 10; deep design in docs/regions.md.