@build-qube/takeoff-calculator 2.0.4 → 2.3.0

package/README.md

@@ -1,3 +1,7 @@
 # `@build-qube/takeoff-calculator`
 
 ![https://github.com/BuildQube/takeoff-calculator/actions](https://github.com/BuildQube/takeoff-calculator/workflows/CI/badge.svg)
+
+## Benchmarks
+
+A performance benchmark suite runs in this package to guard against regressions. See [benchmark/README.md](./benchmark/README.md) for how to run benchmarks locally, interpret results, and CI policy.

package/browser.js

@@ -1 +1 @@
-export * from "@build-qube/takeoff-calculator-wasm32-wasi";
+export * from '@build-qube/takeoff-calculator-wasm32-wasi';

package/index.d.ts

@@ -1,27 +1,86 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+export declare class ContourWrapper {
+  /** Create a new contour wrapper from a contour input. */
+  constructor(contour: ContourInput);
+  /**
+   * Set the scale of the contour.
+   * This will rebuild the surface mesh.
+   */
+  setScale(scale: Scale): void;
+  /** Get the id of the contour. */
+  get id(): string;
+  /** Get the page id of the contour. */
+  get pageId(): string;
+  /** Get the scale of the contour. */
+  get scale(): Scale | null;
+  /** Get the surface points of the contour. */
+  getSurfacePoints(): Array<Point3D> | null;
+  /** Get the z value at the given x and y coordinates. */
+  getZAt(x: number, y: number): number | null;
+  /** Get the scatter data of the contour. */
+  getScatterData(step: number): Array<Point3D> | null;
+  /** Get scaled scatter data of the contour. */
+  getRealWorldScatterData(step: number): Array<Point3D> | null;
+  /** Compute raw cut/fill volume (pixel-space values) against a reference surface. */
+  rawVolumeAgainst(
+    reference: ReferenceSurfaceInput,
+    cellSize?: number | undefined | null,
+  ): VolumetricResult | null;
+  /**
+   * Compute unit-aware cut/fill volume against a reference surface.
+   * Returns None if surface mesh or scale is not available.
+   */
+  volumeAgainst(
+    reference: ReferenceSurfaceInput,
+    cellSize?: number | undefined | null,
+  ): VolumetricUnitResult | null;
+}
+
 export declare class GroupWrapper {
   /** Get the id of the group. */
-  get id(): string
-  get area(): UnitValue | null
-  get length(): UnitValue | null
-  get points(): number | null
-  get count(): number | null
+  get id(): string;
+  /**
+   * Get the area for this group.
+   *
+   * Returns `None` if the area has not been computed or if the mutex is poisoned.
+   */
+  get area(): UnitValue | null;
+  /**
+   * Get the length for this group.
+   *
+   * Returns `None` if the length has not been computed or if the mutex is poisoned.
+   */
+  get length(): UnitValue | null;
+  /**
+   * Get the points count for this group.
+   *
+   * Returns `None` if the points count has not been computed or if the mutex is poisoned.
+   */
+  get points(): number | null;
+  /**
+   * Get the count for this group.
+   *
+   * Returns `None` if the count has not been computed or if the mutex is poisoned.
+   */
+  get count(): number | null;
+  get group(): Group;
 }
 
 export declare class MeasurementWrapper {
-  get points(): number
-  get measurement(): Measurement
-  get area(): UnitValue | null
-  convertArea(unit: Unit): number | null
-  convertLength(unit: Unit): number | null
-  get length(): UnitValue | null
-  get scale(): Scale | null
-  get id(): string
-  get pageId(): string
-  get groupId(): string
-  get rawArea(): number
-  get rawPerimeter(): number
+  get points(): number;
+  get count(): number;
+  get measurement(): Measurement;
+  get area(): UnitValue | null;
+  convertArea(unit: Unit): number | null;
+  convertLength(unit: Unit): number | null;
+  get length(): UnitValue | null;
+  get scale(): Scale | null;
+  get id(): string;
+  get pageId(): string;
+  get groupId(): string;
+  get rawArea(): number;
+  get rawPerimeter(): number;
 }
 
 export declare class TakeoffStateHandler {
@@ -36,8 +95,20 @@ export declare class TakeoffStateHandler {
    *
    * * `State` - The new state.
    */
-  constructor(options?: StateOptions | undefined | null)
-  getMeasurementsByGroupId(groupId: string): Array<MeasurementWrapper>
+  constructor(options?: StateOptions | undefined | null);
+  getMeasurementsByGroupId(groupId: string): Array<MeasurementWrapper>;
+  /**
+   * Get the measurements by page id.
+   *
+   * # Arguments
+   *
+   * * `page_id` - The id of the page.
+   *
+   * # Returns
+   *
+   * * `Vec<MeasurementWrapper>` - The measurements that are on the page.
+   */
+  getMeasurementsByPageId(pageId: string): Array<MeasurementWrapper>;
   /**
    * Get the scale for a measurement.
    *
@@ -50,7 +121,7 @@ export declare class TakeoffStateHandler {
    * * `None` - If the measurement was not found.
    * * `Some(scale)` - If the scale was found.
    */
-  getMeasurementScale(measurementId: string): Scale | null
+  getMeasurementScale(measurementId: string): Scale | null;
   /**
    * Inserts or updates a page in the state.
    *
@@ -63,8 +134,9 @@ export declare class TakeoffStateHandler {
    * * `None` - If the page was not found.
    * * `Some(page)` - If the page was found and updated.
    */
-  upsertPage(page: Page): Page | null
-  getGroup(groupId: string): GroupWrapper | null
+  upsertPage(page: Page): Page | null;
+  removePage(pageId: string): Page | null;
+  getGroup(groupId: string): GroupWrapper | null;
   /**
    * Inserts or updates a group in the state.
    *
@@ -77,7 +149,19 @@ export declare class TakeoffStateHandler {
    * * `None` - If the group was not found.
    * * `Some(group)` - If the group was found and updated.
    */
-  upsertGroup(group: Group): Group | null
+  upsertGroup(group: Group): Group | null;
+  /**
+   * Removes a group from the state.
+   *
+   * # Arguments
+   *
+   * * `group_id` - The id of the group to remove.
+   *
+   * # Returns
+   * * `None` - If the group was not found.
+   * * `Some(group)` - If the group was found and removed.
+   */
+  removeGroup(groupId: string): Group | null;
   /**
    * Inserts or updates a measurement in the state.
    *
@@ -90,8 +174,21 @@ export declare class TakeoffStateHandler {
    * * `None` - If the measurement was not found.
    * * `Some(measurement)` - If the measurement was found and updated.
    */
-  upsertMeasurement(measurement: Measurement): Measurement | null
-  getMeasurement(measurementId: string): MeasurementWrapper | null
+  upsertMeasurement(measurement: Measurement): Measurement | null;
+  /**
+   * Removes a measurement from the state.
+   *
+   * # Arguments
+   *
+   * * `measurement_id` - The id of the measurement to remove.
+   *
+   * # Returns
+   *
+   * * `None` - If the measurement was not found.
+   * * `Some(measurement)` - If the measurement was found and removed.
+   */
+  removeMeasurement(measurementId: string): Measurement | null;
+  getMeasurement(measurementId: string): MeasurementWrapper | null;
   /**
    * Inserts or updates a scale in the state.
    *
@@ -104,7 +201,19 @@ export declare class TakeoffStateHandler {
    * * `None` - If the scale was not found.
    * * `Some(scale)` - If the scale was found and updated.
    */
-  upsertScale(scale: Scale): Scale | null
+  upsertScale(scale: Scale): Scale | null;
+  /**
+   * Removes a scale from the state.
+   *
+   * # Arguments
+   *
+   * * `scale_id` - The id of the scale to remove.
+   *
+   * # Returns
+   * * `None` - If the scale was not found.
+   * * `Some(scale)` - If the scale was found and removed.
+   */
+  removeScale(scaleId: string): Scale | null;
   /**
    * Get the measurements that are missing a scale.
    *
@@ -112,80 +221,209 @@ export declare class TakeoffStateHandler {
    *
    * * `Vec<MeasurementWrapper>` - The measurements that are missing a scale.
    */
-  getMeasurementsMissingScale(): Array<MeasurementWrapper>
+  getMeasurementsMissingScale(): Array<MeasurementWrapper>;
+  upsertContour(input: ContourInput): void;
+  removeContour(contourId: string): boolean;
+  getContour(contourId: string): ContourWrapper | null;
+  getContoursByPageId(pageId: string): Array<ContourWrapper>;
+  getContoursMissingScale(): Array<ContourWrapper>;
+}
 
+export declare class VolumetricUnitResult {
+  get cut(): UnitValue;
+  get fill(): UnitValue;
+  get uncoveredArea(): UnitValue;
 }
 
-export declare function plus100(input: number): number
+/** Add 100 to the input */
+export declare function plus100(input: number): number;
+
+/** Add 200 to the input */
+export declare function plus200(input: number): number;
+
+/** Input for creating a reference surface from JS/TS. */
+export type ReferenceSurfaceInputJs =
+  | { type: 'Polygon'; points: Array<Point>; elevation: number; unit: Unit }
+  | {
+      type: 'Rectangle';
+      points: [Point, Point];
+      elevation: number;
+      unit: Unit;
+    };
 export declare class UnitValue {
-  constructor(value: number, unit: Unit, magnitude: UnitValueItemType)
-  display(unit: Unit): string
-  getConvertedValue(to: Unit): number
+  constructor(value: number, unit: Unit, magnitude: UnitValueItemType);
+  display(unit: Unit): string;
+  getConvertedValue(to: Unit): number;
+}
+
+export interface ContourInput {
+  id: string;
+  name?: string;
+  pageId: string;
+  /** The lines that make up the contour map */
+  lines: Array<ContourLineInput>;
+  /** The points of interest that are used to create the contour map */
+  pointsOfInterest: Array<ContourPointOfInterestInput>;
+}
+
+export interface ContourLineInput {
+  /** The elevation of the contour line (real-world value) */
+  elevation: number;
+  points: Array<Point>;
+  unit: Unit;
 }
 
+export interface ContourPointOfInterestInput {
+  /** The elevation of the point of interest (real-world value) */
+  elevation: number;
+  point: Point;
+  unit: Unit;
+}
+
+/** Calculate distance between two points */
+export declare function distance(
+  points: [Point, Point] | [Point3D, Point3D],
+): number;
+
+/** Generate a random id */
+export declare function generateRandomId(): string;
+
+/**
+ * Get the centroid of a measurement
+ *
+ * Returns `None` if the measurement has invalid geometry.
+ * For more detailed error information, use `measurement.get_centroid()` directly.
+ */
+export declare function getCentroid(measurement: Measurement): Point | null;
+
 export interface Group {
-  id: string
-  name?: string
-  measurementType: MeasurementType
+  id: string;
+  name?: string;
+  measurementType: MeasurementType;
 }
 
 export type Measurement =
-  | { type: 'Count', id: string, pageId: string, groupId: string, points: [Point] }
-  | { type: 'Polygon', id: string, pageId: string, groupId: string, points: Array<Point> }
-  | { type: 'Polyline', id: string, pageId: string, groupId: string, points: Array<Point> }
-  | { type: 'Rectangle', id: string, pageId: string, groupId: string, points: [Point, Point] }
+  | {
+      type: 'Count';
+      id: string;
+      pageId: string;
+      groupId: string;
+      points: [Point];
+    }
+  | {
+      type: 'Polygon';
+      id: string;
+      pageId: string;
+      groupId: string;
+      points: Array<Point>;
+    }
+  | {
+      type: 'Polyline';
+      id: string;
+      pageId: string;
+      groupId: string;
+      points: Array<Point>;
+    }
+  | {
+      type: 'Rectangle';
+      id: string;
+      pageId: string;
+      groupId: string;
+      points: [Point, Point];
+    };
 
-export type MeasurementType =  'Area'|
-'Linear'|
-'Count';
+export type MeasurementType = 'Area' | 'Linear' | 'Count';
 
 export interface Page {
-  id: string
-  name?: string
-  width?: number
-  height?: number
-  viewport?: PageViewport
+  id: string;
+  name?: string;
+  width?: number;
+  height?: number;
+  viewport?: PageViewport;
 }
 
 export interface PageViewport {
-  width: number
-  height: number
+  width: number;
+  height: number;
 }
 
 /** Represents a 2D point with floating point coordinates */
 export interface Point {
-  x: number
-  y: number
+  x: number;
+  y: number;
+}
+
+export interface Point3D {
+  x: number;
+  y: number;
+  z: number;
 }
 
+/** Input for creating a reference surface from JS/TS. */
+export type ReferenceSurfaceInput =
+  | { type: 'Polygon'; points: Array<Point>; elevation: number }
+  | { type: 'Rectangle'; points: [Point, Point]; elevation: number };
+
+/**
+ * Reposition a measurement so its centroid is at the given point.
+ * Returns a new measurement (same kind and metadata); area, length, and count are unchanged.
+ *
+ * # Errors
+ *
+ * Returns an error if the measurement has invalid or empty geometry (e.g. `EmptyGeometry`).
+ */
+export declare function repositionMeasurementToCentroid(
+  measurement: Measurement,
+  newCentroid: Point,
+): Measurement;
+
 export type Scale =
-  | { type: 'Area', id: string, pageId: string, scale: ScaleDefinition, boundingBox: [Point, Point] }
-  | { type: 'Default', id: string, pageId: string, scale: ScaleDefinition }
+  | {
+      type: 'Area';
+      id: string;
+      pageId: string;
+      scale: ScaleDefinition;
+      boundingBox: [Point, Point];
+    }
+  | { type: 'Default'; id: string; pageId: string; scale: ScaleDefinition };
 
 export interface ScaleDefinition {
-  pixelDistance: number
-  realDistance: number
-  unit: Unit
+  pixelDistance: number;
+  realDistance: number;
+  unit: Unit;
 }
 
 /** Simplify a polyline using the Ramer-Douglas-Peucker algorithm */
-export declare function simplifyPolyline(points: Array<Point>, tolerance: number): Array<Point>
+export declare function simplifyPolyline(
+  points: Array<Point>,
+  tolerance: number,
+): Array<Point>;
 
 export interface StateOptions {
-  pages: Array<Page>
-  groups: Array<Group>
-  measurements: Array<Measurement>
-  scales: Array<Scale>
+  pages: Array<Page>;
+  groups: Array<Group>;
+  measurements: Array<Measurement>;
+  scales: Array<Scale>;
 }
 
 /** Measurement units supported by the system */
-export type Unit = /** Imperial units */
-'Yards'|
-'Feet'|
-'Inches'|
-/** Metric units */
-'Meters'|
-'Centimeters';
-
-export type UnitValueItemType =  'Area'|
-'Length';
+export type Unit =
+  /** Imperial units */
+  | 'Yards'
+  | 'Feet'
+  | 'Inches'
+  /** Metric units */
+  | 'Meters'
+  | 'Centimeters';
+
+export type UnitValueItemType = 'Area' | 'Length' | 'Volume';
+
+/** Result of a volumetric cut/fill calculation. */
+export interface VolumetricResult {
+  /** Volume to remove (terrain above reference). */
+  cut: number;
+  /** Volume to add (terrain below reference). */
+  fill: number;
+  /** Area where terrain data was unavailable (z_at returned None). */
+  uncoveredArea: number;
+}