Workshop specification: two geometry functions

We wrote this document for the workshop. It describes the expected behaviour of ClippedArea and ClassifyPoint in the small wrapper we added around Clipper2. The wrappers are in C++ and C#. The repository contains many other library functions; those are outside the core exercise.

Use the rules below when deciding whether the workshop code or a public test needs correction. Code, test names, expected values, and AI explanations can be wrong. If a public test contradicts an explicit rule here, the rule takes precedence.

This is a deliberately limited specification, not a claim that every possible input is fully defined. When it does not answer a question, name the gap rather than inventing a requirement.

Coordinates

Coordinates use signed 64-bit integers. A polygon is a list of vertices; Clipper2 closes the last vertex back to the first, so repeating the first vertex is unnecessary. Rectangles are Rect64(left, top, right, bottom). For example, Rect64(0, 0, 10, 10) has area 100.

Clipped area

ClippedArea(polygon, clip) returns the area of the intersection between a polygon and an axis-aligned clip rectangle, summed across all resulting pieces. The core examples use simple, non-self-intersecting polygons, positive-size rectangles, small coordinates and intersections on integer coordinates.

• The result is non-negative.
• Reversing the polygon's vertex order does not change the result.
• A polygon completely outside the clip rectangle returns 0.
• A polygon covering the clip rectangle returns the rectangle's area.

Point classification

ClassifyPoint(polygon, point) returns one of Outside, Boundary, or Inside.

• Points on an edge or vertex are Boundary.
• Boundary is neither Inside nor Outside.
• Reversing the polygon's vertex order does not change the classification.

Questions this document does not settle

The rules do not fully define input validity, self-intersecting polygons, repeated or insufficient vertices, zero-size rectangles, inverted rectangles, or numerical accuracy at very large coordinates. Clipper2 stores clipping results on an integer grid: non-integer intersection vertices can be rounded, so exact mathematical area is not promised for those inputs. A 64-bit coordinate type alone does not establish an accuracy guarantee across its entire range. The area return type is floating point.

The core exercises use small, simple polygons. Extra exercises 5, 6, 14, and 15 deliberately investigate less-defined cases. For those, separate what the implementation did from what this document promises. Proposed new rules belong in docs/spec-proposals.md; do not silently treat them as existing requirements.