Query: Circle

Circle-specific geometry queries — read closed-circle properties as plain values. A circle is a closed curve with its own namespace (mirroring the arc query surface); it is not part of the shared CurveHandle line/arc surface. Every method takes an opaque CircleHandle (plus a point handle where relevant) and returns plain values — numbers, Vec3Components, predicates as boolean. No query mutates its inputs. Accessed via snaptrude.core.geom.query.circle.

Types

Vec3Components

Plain-value record returned by point/vector reads (see Handles).

Property	Type	Description
x	number	X component
y	number	Y component
z	number	Z component

Functions

getRadius(circle)

Read the radius of a circle.

• Parameters:
  • circle: CircleHandle — The circle to query
• Returns: number — The radius

const { vec3 } = snaptrude.core.math;
const { create, query } = snaptrude.core.geom;

const centrePoint = await vec3.new(0, 0, 0);
const axis = await vec3.new(0, 1, 0);
const circle = await create.circle(centrePoint, axis, 2);

const radius = await query.circle.getRadius(circle); // 2

---

getCentre(circle)

Read the centre point of a circle.

• Parameters:
  • circle: CircleHandle — The circle to query
• Returns: Vec3Components — The centre as plain { x, y, z }

const centre = await snaptrude.core.geom.query.circle.getCentre(circle);
// { x: 0, y: 0, z: 0 }

---

getAxis(circle)

Read the axis (plane normal) of a circle.

• Parameters:
  • circle: CircleHandle — The circle to query
• Returns: Vec3Components — The axis as plain { x, y, z }

---

getLength(circle)

Read the length (circumference, 2πr) of a circle.

• Parameters:
  • circle: CircleHandle — The circle to query
• Returns: number — The circumference

---

isValid(circle)

Check whether a circle is geometrically valid (non-degenerate axis + positive radius).

• Parameters:
  • circle: CircleHandle — The circle to query
• Returns: boolean — true if the circle is valid, otherwise false

---

getNearestPoint(circle, point)

Get the point on a circle nearest to an arbitrary point.

• Parameters:
  • circle: CircleHandle — The circle to query
  • point: Vec3Handle — The reference point
• Returns: Vec3Components — The nearest point on the circle

---

hasPoint(circle, point)

Test whether a point lies on a circle.

• Parameters:
  • circle: CircleHandle — The circle to query
  • point: Vec3Handle — The point to test
• Returns: boolean — true if the point is on the circle, otherwise false

---

getTangent(circle, point)

Get the tangent direction of a circle at a point on it.

• Parameters:
  • circle: CircleHandle — The circle to query
  • point: Vec3Handle — A point on the circle
• Returns: Vec3Components — The tangent direction

---

getNormal(circle, point)

Get the (in-plane, radial) normal direction of a circle at a point on it.

• Parameters:
  • circle: CircleHandle — The circle to query
  • point: Vec3Handle — A point on the circle
• Returns: Vec3Components — The radial normal direction

---

getPointAtDistance(circle, referencePoint, distance, forward?)

Get the point reached by travelling a signed arc-distance along the circle from a reference point that lies on it.

• Parameters:
  • circle: CircleHandle — The circle to query
  • referencePoint: Vec3Handle — A point on the circle to travel from
  • distance: number — Arc distance to travel
  • forward: boolean (optional, default forward) — Travel direction
• Returns: Vec3Components — The resulting point

const { vec3 } = snaptrude.core.math;
const { query } = snaptrude.core.geom;

// Walk a quarter of the circumference along the circle
const start = await vec3.new(2, 0, 0);
const circumference = await query.circle.getLength(circle);
const point = await query.circle.getPointAtDistance(circle, start, circumference / 4);

---

isEqual(circleA, circleB)

Test whether two circles are geometrically equal.

• Parameters:
  • circleA: CircleHandle — First circle
  • circleB: CircleHandle — Second circle
• Returns: boolean — true if the circles are equal, otherwise false

---

listPoints(circle, resolution?)

Sample a circle into an ordered list of points.

• Parameters:
  • circle: CircleHandle — The circle to query
  • resolution: number (optional) — Number of segments to sample
• Returns: Vec3Components[] — The sampled points

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
HANDLE_INVALID	all methods	The circle or point handle is invalid, stale, or foreign	—

Beyond handle resolution these reads are total — they never throw for a resolvable circle.