contours module#

Coordinate hygiene at the rounding boundary.

Everything here exists because rounding to the output grid is what creates the constructs 4.10.3 forbids, not what removes them: a shapely-derived outline routinely carries vertices less than a nanometer apart, and three points of a shallow curve become exactly collinear once they land on the grid. So the scrubbing runs after the coordinates are quantized, and the same rules apply to a macro outline primitive as to a region contour - 4.5.1.6 says an outline “must comply with all the requirements of a contour according to 4.10.3”.

MIN_ARC_MM = 0.002#

Arcs shorter than this are emitted as draws; below it the center is numerically meaningless at the coordinate resolution.

exception ContourError[source]#

Bases: ValueError

A contour cannot be made to satisfy 4.10.3.

arc_angles(start, end, center, ccw)[source]#

The start angle and signed sweep of an arc, in radians.

The sweep is positive counter-clockwise. A coincident start and end is a full circle, which takes the full turn in the requested direction rather than a zero sweep.

Return type:

tuple[float, float]

Parameters:
split_arc(start, end, center, ccw)[source]#

Intermediate points splitting an arc into sweeps of at most 180°.

Returns the points between start and end, in order; empty when the arc already fits. The spec singles out near-full arcs as numerically unstable, and a full circle has no valid single-segment form inside a contour at all.

Return type:

list[tuple[float, float]]

Parameters:
arc_length(start, end, center, ccw)[source]#

Arc length in mm.

Return type:

float

Parameters:
scrub(contour)[source]#

Put a contour on the output grid and make it satisfy 4.10.3.

Snaps every coordinate, drops zero-length and collinear straight segments, turns sub-resolution arcs into straight segments, splits arcs over 180 degrees, and verifies the closure holds after rounding rather than before it.

Raises:

ContourError – nothing survives the scrubbing, or the contour does not close on the grid.

Return type:

Contour

Parameters:

contour (Contour)

validate(contour)[source]#

Check a scrubbed contour against 4.10.3.

Self-intersection is not checked here; it needs real geometry and the format layer carries no shapely dependency, so §8’s polarity layer owns it.

Raises:

ContourError – a zero-length segment, a collinear vertex or an open contour survived.

Return type:

None

Parameters:

contour (Contour)

closed_ring(points)[source]#

A contour from a point ring, closing it if the caller has not.

The convention this package fixes, because the spec leaves it open and §8’s polarity simulator needs one to interpret: outer contours run counter-clockwise, holes clockwise. This helper does not reorder; it is the callers that owe the convention.

Return type:

Contour

Parameters:

points (list[tuple[float, float]])

signed_area(contour)[source]#

Twice the signed polygon area of a contour’s vertices, in mm².

Positive is counter-clockwise. Arc bulges are ignored, so this is for checking and fixing winding, not for measuring.

Return type:

float

Parameters:

contour (Contour)