PolyPrune Outer Approximation

Deterministic outer-approximation helper for GeoJSON polygons.

Install

npm install poly-prune

What It Guarantees

• Strict containment: output polygon never cuts inside the original polygon.
• Exact vertex count: output has exactly targetVertexCount vertices.
• Minimum deviation objective: algorithm minimizes outward deviation for the requested target.
• maxDeviation is only an upper limit (optional), never the optimization target.
• Deterministic output: same input always returns the same result.

API

outerApproximatePolygon(input: {
  originalPolygon: GeoJSONPolygon;
  targetVertexCount: number;
  maxDeviation?: number;
}): {
  polygon: GeoJSONPolygon;
  achievedDeviation: number;
  maxDeviation: number;
  maxDeviationProvided: boolean;
}

Inputs

• input: object with:
  • originalPolygon: GeoJSON Polygon geometry (single outer ring, no holes).
  • targetVertexCount: integer >= 3.
  • maxDeviation (optional): non-negative numeric cap.

Output Fields

• polygon: resulting outer polygon.
• achievedDeviation: measured outward deviation of result.
• maxDeviation: provided cap, or inferred value (achievedDeviation) when omitted.
• maxDeviationProvided: true if caller passed maxDeviation.

Behavior Rules

1. Minimize deviation first.
2. If maxDeviation is provided, return only if achievedDeviation <= maxDeviation.
3. If impossible under cap, throws OuterApproximationError with code TARGET_NOT_REACHABLE.

Examples

CommonJS

const { outerApproximatePolygon } = require('poly-prune');

const result = outerApproximatePolygon({
  originalPolygon: polygon,
  targetVertexCount: 4,
  maxDeviation: 0.005,
});
console.log(result.achievedDeviation);
console.log(JSON.stringify(result.polygon));

TypeScript

import { outerApproximatePolygon } from 'poly-prune';

const result = outerApproximatePolygon({
  originalPolygon: polygon,
  targetVertexCount: 4,
});

Error Handling (Public API)

The library throws OuterApproximationError with stable code values and structured details.

const {
  outerApproximatePolygon,
  OuterApproximationError,
  OUTER_APPROXIMATION_ERROR_CODES,
} = require('poly-prune');

try {
  const result = outerApproximatePolygon({
    originalPolygon: polygon,
    targetVertexCount: 4,
    maxDeviation: 0.005,
  });
  console.log(result.polygon);
} catch (error) {
  if (error instanceof OuterApproximationError) {
    if (error.code === OUTER_APPROXIMATION_ERROR_CODES.TARGET_NOT_REACHABLE) {
      console.error('Not feasible under maxDeviation', error.details);
    } else {
      console.error('Invalid input', error.code, error.details);
    }
  } else {
    throw error;
  }
}

Common Error Codes

• TARGET_NOT_REACHABLE
• INVALID_INPUT
• INVALID_GEOMETRY

For finer diagnosis, inspect error.details.reason (for example: INVALID_POLYGON_TYPE, RING_NOT_CLOSED).

Local Development

• Run tests: npm test
• Preview package artifact: npm run pack:check

Publish Checklist

1. Update name if needed (must be unique on npm).
2. Update version (semver).
3. npm test
4. npm run pack:check
5. npm login
6. npm publish --access public