Rectangle Fitting Rules

Purpose

This note defines the rectangle-fitting rules used when HAPI converts surveyed coordinates into a mathematically regular enclosing rectangle.

Source Priority

1. User-confirmed project correction
2. Rectangle-fitting Algorithms.md
3. HAPI User Manual.pdf
4. Point Code and Style Code.md

Confirmed Manual Correction

The HAPI User Manual describes Shrink to Fit as selecting the smallest-area rectangle. This has been superseded by the user-confirmed project rule:

Shrink to Fit Mode uses Minimum Perimeter, not Minimum Area.

Foundation and implementation notes should therefore use:

Score = Width + Height

The candidate rectangle with the lowest score is selected.

Objective

Transform a list of surveyed 3D coordinates into exactly four mathematically regular corner points representing an enclosing rectangle.

List<Point3d> → 4 ordered rectangle corner points

Algorithm 1: Best-fit

Behavioural Summary

Best-fit solves the common three-point survey problem. It identifies the surveyed vertex closest to a true 90-degree corner and aligns the local coordinate system to that corner.

Execution Logic

1. Project input 3D points onto the XY plane for angle analysis.
2. Generate directional vectors between sequential points.
3. Calculate internal angles using vector dot products.
4. Score each angle by its deviation from 90 degrees.
5. Select the anchor vertex with the smallest deviation.
6. Build a local coordinate system aligned with the winning vector.
7. Transform the original 3D points into local coordinates.
8. Generate an axis-aligned bounding box in local space.
9. Extract four local corners.
10. Transform the corners back into world coordinates.
11. Apply Universal Orientation Stabilisation.

Recommended Use

Best-fit is preferred for standard rectangular objects where the surveyed points are expected to reflect a true rectangular feature.

Algorithm 2: Shrink to Fit

Behavioural Summary

Shrink to Fit tests candidate orientations and selects the most compact box-like boundary by Minimum Perimeter.

This penalises long, thin candidate rectangles and is more suitable for noisy or irregular point groups.

Execution Logic

1. Project input 3D points onto the XY plane.
2. Generate candidate axes from sequential point segments.
3. For each candidate axis, build a local coordinate system.
4. Transform the point cloud into each candidate coordinate system.
5. Calculate the axis-aligned bounding box for each candidate.
6. Calculate the perimeter score:

Width  = Max.X - Min.X
Height = Max.Y - Min.Y
Score  = Width + Height

7. Select the candidate with the lowest score.
8. Recalculate the final AABB in the winning coordinate system.
9. Extract four local corners.
10. Transform the corners back to world coordinates.
11. Apply Universal Orientation Stabilisation.

Recommended Use

Shrink to Fit is preferred for irregular point groupings, noisy datasets, or features that are not perfectly rectangular.

Universal Orientation Stabilisation

After either rectangle-fitting algorithm, the final corner sequence must be stabilised.

Rule

The starting position should be based on the left-most midpoint of the rectangle's short edge. This prevents downstream text, symbols, or blocks from appearing upside down or right-to-left.

Execution Logic

1. Calculate edge lengths for the four rectangle edges.
2. Detect whether the shape is effectively square:

IsSquare = (MaxLength - MinLength) < 0.001

3. Calculate all edge midpoints.
4. If square, keep all midpoints as candidates.
5. If not square, keep only the midpoints of the two shortest edges.
6. Sort candidate midpoints using:

SortScore = (XCoordinate * 100000) + YCoordinate

7. Select the lowest score.
8. Reorder the rectangle points to begin on the edge associated with the winning midpoint, proceeding counter-clockwise.

Preferred Function Names

Related Notes

• Sizing_Number
• Point_Code_Grouping_Rules
• Feature_Type
• Feature_Catalogue

Open Questions

• Confirm whether Z values in the returned rectangle corners should preserve minimum Z, average Z, or source-point-specific Z according to the intended ECM downstream workflow.