Sketches and constraints

Author planar profiles with explicit entities, loops, holes, and the built-in constraint solver.

Sketches define planar profiles for extrusion, revolution, lofting, and sweeps. The callback receives a SketchBuilder and must return exactly one sketch.profile(...).

Planes

const xy = plane.xy();
const elevated = plane.xy(vec3(mm(0), mm(0), mm(30)));
const yz = plane.yz();
const xz = plane.xz();

Document 0.1 supports the three principal plane orientations with an optional parameterized origin.

A profile with holes

const profile = cad.sketch("flange-profile", plane.xy(), (sketch) => {
  const outline = sketch.rectangle("outline", {
    width: mm(80),
    height: mm(50),
  });
  const left = sketch.circle("left-hole", {
    center: vec2(mm(-25), mm(0)),
    radius: mm(4),
  });
  const right = sketch.circle("right-hole", {
    center: vec2(mm(25), mm(0)),
    radius: mm(4),
  });

  return sketch.profile(outline, {
    holes: [left.loop(), right.loop()],
  });
});

Profiles have one explicit outer loop and zero or more explicit hole loops. The evaluator does not infer which disconnected loop is outer from enumeration order. These roles are explicit modeling intent: traversal winding does not turn a declared hole into an outer loop or an outer loop into a hole. Profiles do not currently express islands or general multi-region region algebra.

Entities

SketchBuilder supports:

• point(id, position)
• line(id, start, end)
• circle(id, { center, radius })
• arc(id, { center, radius, startAngle, endAngle })
• polyline(id, points, { closed })
• rectangle(id, options)
• regularPolygon(id, sides, radius, options)

Use sketch.loop([...]) to assemble ordered lines and arcs. Reverse an edge use when the loop traversal runs opposite its authored direction. A loop must be closed and non-self-intersecting after solving.

Constraint example

const profile = cad.sketch("constrained-profile", plane.xy(), (sketch) => {
  const a = sketch.point("a", vec2(mm(0), mm(0)));
  const b = sketch.point("b", vec2(mm(40), mm(0)));
  const c = sketch.point("c", vec2(mm(40), mm(20)));
  const d = sketch.point("d", vec2(mm(0), mm(20)));

  const bottom = sketch.line("bottom", a, b);
  const right = sketch.line("right", b, c);
  const top = sketch.line("top", c, d);
  const left = sketch.line("left", d, a);

  sketch
    .fixed("anchor", a)
    .horizontal("bottom-horizontal", bottom)
    .horizontal("top-horizontal", top)
    .vertical("right-vertical", right)
    .vertical("left-vertical", left)
    .length("width", bottom, mm(40))
    .length("height", left, mm(20));

  return sketch.profile(sketch.loop([bottom, right, top, left]));
});

Supported constraints

Category	Constraints
Position	coincident, fixed, midpoint
Orientation	horizontal, vertical, parallel, perpendicular, angle
Distance	point distance, X distance, Y distance, line length
Equality	equal length, equal radius
Curves	radius, diameter, line-circle tangent

The built-in solver is a permissively licensed reference implementation for 0.1. It is replaceable through the sketch-solver protocol. Industrial conflict isolation, redundant-constraint explanations, drag solving, and large sparse systems remain roadmap items.

Tolerance and validity

cad.sketch("precision-profile", plane.xy(), buildProfile, {
  tolerance: 1e-7,
});

Tolerance is a positive finite number in millimetres. It affects sketch solution and profile validity checks; it is not permission to accept arbitrary gaps.

After the final call-time parameter and named-configuration values are resolved, the evaluator validates the solved profile before handing it to a dependent geometry-kernel feature. When a profile declares holes, its resolved loops must be finite, nondegenerate, closed, and simple enough for the current single-outer-region contract. Every hole boundary must have clearance strictly greater than the sketch tolerance from the outer boundary and every other hole boundary. A hole that is disjoint but outside the outer loop, encloses it, touches it, crosses or partially overlaps it, or coincides with it is rejected. Distinct holes likewise cannot touch, intersect, coincide, or nest. After the same bounded and cancellable closure gate used for every solved profile, hole-free profiles retain their existing feature-specific geometric admission and diagnostics.

This evaluator-side hole-region decision is kernel-neutral, so Manifold, OCCT, and a custom kernel used through Evaluator receive the same decision. Invalid regions fail before the profile reaches a dependent kernel call with SKETCH_NO_CLOSED_REGION. Relationship and self-contact diagnostics identify the sketch and resolved loop index where available, and retain an implicated entity only when solver provenance exactly matches the authored loop and curve. Closure failures retain the established profile-scoped diagnostic. Explicit outer/hole roles remain independent of clockwise or counterclockwise traversal.

The validator uses analytic line, arc, and circle predicates plus adaptive chord-sagitta bounds for separation proofs. Curve segments values are rendering/backend tessellation hints and do not relax or discretize this decision. The closure and hole-region checks share a cumulative work ceiling per sketch, sourced from DEFAULT_DESIGN_DOCUMENT_LIMITS.maxStructuralValues, and the evaluation abort signal. Exhausting the ceiling returns RESOURCE_LIMIT_EXCEEDED, cancellation returns EVALUATION_ABORTED, and a numerically uncertain clearance fails closed.

This guarantee belongs to document evaluation. A direct low-level GeometryKernel profile call bypasses the evaluator boundary and must satisfy the kernel’s resolved-profile contract itself. InvariantCAD does not clamp, move, or reinterpret an invalid hole, and it does not derive relational parameter bounds automatically.

Stable entity IDs

Entity IDs are later available as sketch-source topology provenance. If a fillet intends the extrusion side created by outline.e1, select that source explicitly rather than relying on geometric position. Preserve entity IDs when refactoring a sketch if downstream topology intent should remain stable.