@build-qube/takeoff-calculator 2.1.0 → 2.3.0

package/index.d.ts

@@ -1,190 +1,238 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 export declare class ContourWrapper {
-	constructor(contour: ContourInput);
-	/** Get the surface points for the contour. */
-	getSurfacePoints(): Array<Point3D> | null;
-	/**
-	 * Compute cut/fill volume against a reference surface.
-	 * Returns None if the surface mesh is not available (e.g. contour conversion failed).
-	 */
-	volumeAgainst(
-		reference: ReferenceSurfaceInput,
-		cellSize?: number | undefined | null,
-	): VolumetricResult | null;
-	/**
-	 * Get the z value at a given x, y coordinate.
-	 * Returns None if the surface mesh is not available (e.g. contour conversion failed).
-	 */
-	getZAt(x: number, y: number): number | null;
-	/**
-	 * Get scatter data for the contour.
-	 * Returns None if the surface mesh is not available (e.g. contour conversion failed).
-	 *
-	 * # Arguments
-	 *
-	 * * `step` - The step size for the scatter data.
-	 *
-	 * # Returns
-	 *
-	 * * `Vec<Point3D>` - The scatter data.
-	 * * `None` - If the surface mesh is not available (e.g. contour conversion failed).
-	 */
-	getScatterData(step: number): Array<Point3D> | null;
+  /** 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 group(): Group;
+  /** Get the id of the group. */
+  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 {
-	/**
-	 * Creates a new state.
-	 *
-	 * # Arguments
-	 *
-	 * * `options` - The options for the state.
-	 *
-	 * # Returns
-	 *
-	 * * `State` - The new state.
-	 */
-	constructor(options?: StateOptions | undefined | null);
-	getMeasurementsByGroupId(groupId: string): Array<MeasurementWrapper>;
-	/**
-	 * Get the scale for a measurement.
-	 *
-	 * # Arguments
-	 *
-	 * * `measurement_id` - The id of the measurement.
-	 *
-	 * # Returns
-	 *
-	 * * `None` - If the measurement was not found.
-	 * * `Some(scale)` - If the scale was found.
-	 */
-	getMeasurementScale(measurementId: string): Scale | null;
-	/**
-	 * Inserts or updates a page in the state.
-	 *
-	 * # Arguments
-	 *
-	 * * `page` - The page to insert or update.
-	 *
-	 * # Returns
-	 *
-	 * * `None` - If the page was not found.
-	 * * `Some(page)` - If the page was found and updated.
-	 */
-	upsertPage(page: Page): Page | null;
-	removePage(pageId: string): Page | null;
-	getGroup(groupId: string): GroupWrapper | null;
-	/**
-	 * Inserts or updates a group in the state.
-	 *
-	 * # Arguments
-	 *
-	 * * `group` - The group to insert or update.
-	 *
-	 * # Returns
-	 *
-	 * * `None` - If the group was not found.
-	 * * `Some(group)` - If the group was found and updated.
-	 */
-	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.
-	 *
-	 * # Arguments
-	 *
-	 * * `measurement` - The measurement to insert or update.
-	 *
-	 * # Returns
-	 *
-	 * * `None` - If the measurement was not found.
-	 * * `Some(measurement)` - If the measurement was found and updated.
-	 */
-	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.
-	 *
-	 * # Arguments
-	 *
-	 * * `scale` - The scale to insert or update.
-	 *
-	 * # Returns
-	 *
-	 * * `None` - If the scale was not found.
-	 * * `Some(scale)` - If the scale was found and updated.
-	 */
-	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.
-	 *
-	 * # Returns
-	 *
-	 * * `Vec<MeasurementWrapper>` - The measurements that are missing a scale.
-	 */
-	getMeasurementsMissingScale(): Array<MeasurementWrapper>;
+  /**
+   * Creates a new state.
+   *
+   * # Arguments
+   *
+   * * `options` - The options for the state.
+   *
+   * # Returns
+   *
+   * * `State` - The new state.
+   */
+  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.
+   *
+   * # Arguments
+   *
+   * * `measurement_id` - The id of the measurement.
+   *
+   * # Returns
+   *
+   * * `None` - If the measurement was not found.
+   * * `Some(scale)` - If the scale was found.
+   */
+  getMeasurementScale(measurementId: string): Scale | null;
+  /**
+   * Inserts or updates a page in the state.
+   *
+   * # Arguments
+   *
+   * * `page` - The page to insert or update.
+   *
+   * # Returns
+   *
+   * * `None` - If the page was not found.
+   * * `Some(page)` - If the page was found and updated.
+   */
+  upsertPage(page: Page): Page | null;
+  removePage(pageId: string): Page | null;
+  getGroup(groupId: string): GroupWrapper | null;
+  /**
+   * Inserts or updates a group in the state.
+   *
+   * # Arguments
+   *
+   * * `group` - The group to insert or update.
+   *
+   * # Returns
+   *
+   * * `None` - If the group was not found.
+   * * `Some(group)` - If the group was found and updated.
+   */
+  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.
+   *
+   * # Arguments
+   *
+   * * `measurement` - The measurement to insert or update.
+   *
+   * # Returns
+   *
+   * * `None` - If the measurement was not found.
+   * * `Some(measurement)` - If the measurement was found and updated.
+   */
+  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.
+   *
+   * # Arguments
+   *
+   * * `scale` - The scale to insert or update.
+   *
+   * # Returns
+   *
+   * * `None` - If the scale was not found.
+   * * `Some(scale)` - If the scale was found and updated.
+   */
+  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.
+   *
+   * # Returns
+   *
+   * * `Vec<MeasurementWrapper>` - The measurements that are missing a scale.
+   */
+  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;
 }
 
 /** Add 100 to the input */
@@ -192,157 +240,190 @@ 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>;
+  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 (in pixels) */
-	elevation: number;
-	points: Array<Point>;
+  /** 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 (in pixels) */
-	elevation: number;
-	point: Point;
+  /** 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],
+  points: [Point, Point] | [Point3D, Point3D],
 ): number;
 
-/** Get the centroid of a measurement */
+/** 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;
+  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 };
+  | { 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,
+  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";
+  /** Imperial units */
+  | 'Yards'
+  | 'Feet'
+  | 'Inches'
+  /** Metric units */
+  | 'Meters'
+  | 'Centimeters';
 
-export type UnitValueItemType = "Area" | "Length";
+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;
+  /** 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;
 }