@bettermedicine/imeasure 0.0.3 → 0.0.4

package/dist/formatting/interactive.d.ts

@@ -1,7 +1,15 @@
 import { TInteractiveIMeasureModeClicks } from "../types/io";
 import { TWorldMetadata, TCropMetadata } from "../types/metadata";
+/**
+ * @internal
+ * TODO: interactive docs
+ */
 export type TInteractiveImeasureInput = {
     id: string;
     clicks: TInteractiveIMeasureModeClicks[];
 } & TWorldMetadata & TCropMetadata;
+/**
+ * @internal
+ * TODO: interactive docs
+ */
 export declare const formatInteractivePayload: (input: TInteractiveImeasureInput, image: Int16Array, mask?: Uint8Array) => import("undici-types").FormData;

package/dist/formatting/interactive.js

@@ -1,4 +1,8 @@
 import { vec3ToPoint3D } from "./utils";
+/**
+ * @internal
+ * TODO: interactive docs
+ */
 export const formatInteractivePayload = (input, image, mask) => {
     const fd = new FormData();
     const metadata = {

package/dist/types/io.d.ts

@@ -1,26 +1,121 @@
 import { Point3D } from "./cornerstone";
+/**
+ * Represents a raw measurement between two points in both voxel and world spaces.
+ *
+ * @property coords_voxel - The start and end points of the measurement in voxel-space coordinates.
+ * @property coords_world - The start and end points of the measurement in world-space coordinates.
+ * @property length_voxel - The distance between the two points in voxel space.
+ * @property length_world - The distance between the two points in world space.
+ */
 export type TRawMeasurement = {
     coords_voxel: [Point3D, Point3D];
     coords_world: [Point3D, Point3D];
     length_voxel: number;
     length_world: number;
 };
+/**
+ * Represents a cross measurement consisting of two raw measurements.
+ *
+ * @property short - The shorter measurement in the cross.
+ * @property long - The longer measurement in the cross.
+ */
 export type TCrossMeasurement = {
     short: TRawMeasurement;
     long: TRawMeasurement;
 };
+/**
+ * Represents a collection of measurements derived from the resulting segmentation mask.
+ *
+ * @property cross - Contains measurements for the cross section, with the key "2" representing the axial plane.
+ * @property diagonal - Represents the diagonal measurement.
+ * @property height - Represents the height measurement.
+ * @privateRemarks
+ * the key of "2" should be replaced with a more descriptive name in the future, eg. "axial"
+ */
+export type TMeasurements = {
+    cross: {
+        2: TCrossMeasurement;
+    };
+    diagonal: TRawMeasurement;
+    height: TRawMeasurement;
+};
+/**
+ * The return type of the static IMeasure 3D API endpoint.
+ *
+ * @property mask - A base64-encoded string that represents the flattened 3D segmentation mask.
+ * The mask is a binary representation of the segmentation, with `0` representing background voxels and `1` representing foreground voxels.
+ * To marshal it into a 3D mask, the client should convert the base64 string into an array of numbers and reshape it
+ * to conform to the returned `mask_shape` property.
+ * @property measurements - An object containing cross, diagonal, and height measurements.
+ * @property volume_mm3 - The volume of the segmentation in cubic millimeters.
+ * @property volume - The volume of the segmentation in voxels.
+ * @property mask_shape - The shape of the mask in voxels, represented as a tuple of three integers (x, y, z).
+ * @property mask_spacing - The world-space spacing of the mask in voxel coordinates, represented as a tuple of three floats (x, y, z).
+ * @property mask_origin_voxel - The origin of the mask in voxel coordinates, represented as a tuple of three integers (x, y, z).
+ *
+ * @interface
+ */
 export type TIMeasure3DResponse = {
     mask: string;
-    measurements: {
-        cross: {
-            0: TCrossMeasurement;
-            1: TCrossMeasurement;
-            2: TCrossMeasurement;
-        };
-        diagonal: TRawMeasurement;
-        height: TRawMeasurement;
-    };
+    measurements: TMeasurements;
+    volume_mm3: number;
+    volume: number;
+    mask_shape: [number, number, number];
+    mask_spacing: Point3D;
+    mask_origin_voxel: Point3D;
 };
+/**
+ * The generic input type for the `metadata` part of an iMeasure request, expended by the default Static and experimental
+ * Interactive iMeasure variants.
+ *
+ * This type is used to define the metadata that is sent along with the iMeasure request and should be included
+ * in the multipart FormData request body as a `Blob`:
+ * ```typescript
+ * const formData = new FormData();
+ * formData.append("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }));
+ * ```
+ *
+ * @see the function {@link metadata.extractWorldMetaFromImageDataAndDisplaySet | extractWorldMetaFromImageDataAndDisplaySet} for deriving the following properties from a VTK volume and an OHIF displayset:
+ *   - * `worldOrigin`
+ *   - * `worldShape`
+ *   - * `worldSpacing`
+ *   - * `worldBoundingImagePositions`
+ *   - * `imageCount`
+ *   - * `rescaleIntercept`
+ *   - * `rescaleSlope`
+ *   - * `imageOrientationPatient`
+ * @see the function {@link math.cropping.calculateStaticImeasureBoundingBox | calculateStaticImeasureBoundingBox} in for deriving the following properties from user clicks and world affines:
+ *   - * `cropBoundariesWorld`
+ *   - * `cropBoundariesVoxel`
+ *   - * `cropBoundariesUnclippedVoxel`
+ *   - * `cropCuboidCenterVoxel`
+ *   - * `shape`
+ *
+ * @see the {@link formatting.formatStaticPayload | formatStaticPayload} function for an utility function for constructing the FormData
+ * payload from an union of {@link Types.Metadata.TWorldMetadata | TWorldMetadata}, {@link Types.Metadata.TCropMetadata | TCropMetadata} and parsed image data.
+ *
+ * @property id - A unique UUID4-compliant identifier for the measurement.
+ * @property world_origin - The origin of the world coordinate system in world-space, represented as a tuple of three floats (x, y, z).
+ * @property world_shape - The shape of the world voxel space, represented as a tuple of three integers (x, y, z) - eg. [512, 512, 100].
+ * @property world_spacing - The spacing of the world voxel space, represented as a tuple of three floats (x, y, z).
+ * @property rescale_intercept - The rescale intercept value for the underlying series, used to adjust/normalize pixel values.
+ * @property rescale_slope - The rescale slope value for the underlying series, used to adjust/normalize pixel values.
+ * @property image_orientation_patient - The image orientation in patient coordinates, represented as a tuple of six floats
+ * (x1, y1, z1, x2, y2, z2), where (x1, y1, z1) and (x2, y2, z2) are the direction cosines of the image axes.
+ * @property crop_boundaries_world - The boundaries of the crop region in world coordinates, represented as a tuple of two Point3D objects
+ * (minPoint, maxPoint), where minPoint and maxPoint are the minimum and maximum points of the crop region in world space.
+ * @property crop_boundaries_voxel - The boundaries of the crop region in voxel coordinates, represented as a tuple of two Point3D objects
+ * (minPoint, maxPoint), where minPoint and maxPoint are the minimum and maximum points of the crop region in voxel space.
+ * @property crop_boundaries_unclipped_voxel - The unclipped boundaries of the crop region in voxel coordinates,
+ * represented as a tuple of two Point3D objects (minPoint, maxPoint),
+ * where minPoint and maxPoint are the minimum and maximum points of the crop region in voxel space before clipping.
+ * @property crop_cuboid_center_voxel - The center of the crop cuboid in voxel coordinates, represented as a
+ * Point3D object (x, y, z), where (x, y, z) are the coordinates of the center point of the crop cuboid in voxel space before clipping.
+ * @property shape - The shape of the cropped volume, represented as a tuple of three integers (x, y, z).
+ * @property world_bounding_image_positions - Effectively the ImagePositionPatient values for the first and last images in the series,
+ * represented as a tuple of two Point3D objects (firstPosition, lastPosition).
+ * @property image_count - The number of images in the entire series.
+ */
 export type TIMeasure3DGenericPayload = {
     id: string;
     world_origin: Point3D;
@@ -37,15 +132,35 @@ export type TIMeasure3DGenericPayload = {
     world_bounding_image_positions: [Point3D, Point3D];
     image_count: number;
 };
-export type TStaticImeasurePayload = TIMeasure3DGenericPayload & {
+/**
+ * The shape of the payload for static iMeasure operations.
+ *
+ * @remarks
+ * This type extends {@link TIMeasure3DGenericPayload}, inheriting all its properties,
+ * and adds a `clicks` property representing two 3D points.
+ *
+ * @property clicks - A tuple containing two {@link Point3D} objects, representing the selected points in 3D space.
+ *
+ * @see {@link TIMeasure3DGenericPayload} for inherited properties and additional context.
+ */
+export interface IStaticIMeasurePayload extends TIMeasure3DGenericPayload {
     clicks: [Point3D, Point3D];
-};
+}
+/**
+ * @internal
+ */
 export type TInteractiveIMeasureMode = "positive" | "negative";
+/**
+ * @internal
+ */
 export type TInteractiveIMeasureModeClicks = {
     mode: TInteractiveIMeasureMode;
     points: Point3D[];
     firstClick?: true;
 };
+/**
+ * @internal
+ */
 export type TInteractiveImeasurePayload = TIMeasure3DGenericPayload & {
     finding_id?: string;
     clicks: TInteractiveIMeasureModeClicks[];

package/docs/docusaurus.config.ts

@@ -126,6 +126,7 @@ const config: Config = {
         sidebar: {
           autoConfiguration: false,
         },
+        excludeInternal: true,
       },
     ],
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettermedicine/imeasure",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "main": "dist/index.js",
   "scripts": {
     "prepack": "npm run build",

package/src/formatting/interactive.ts

@@ -5,12 +5,19 @@ import {
 import { TWorldMetadata, TCropMetadata } from "../types/metadata";
 import { vec3ToPoint3D } from "./utils";
 
+/**
+ * @internal
+ * TODO: interactive docs
+ */
 export type TInteractiveImeasureInput = {
   id: string;
   clicks: TInteractiveIMeasureModeClicks[];
 } & TWorldMetadata &
   TCropMetadata;
-
+/**
+ * @internal
+ * TODO: interactive docs
+ */
 export const formatInteractivePayload = (
   input: TInteractiveImeasureInput,
   image: Int16Array,

package/src/formatting/static.ts

@@ -1,5 +1,5 @@
 import { Point3D } from "../types/cornerstone";
-import { TStaticImeasurePayload } from "../types/io";
+import { IStaticIMeasurePayload } from "../types/io";
 import { TWorldMetadata, TCropMetadata } from "../types/metadata";
 import { vec3ToPoint3D } from "./utils";
 
@@ -14,7 +14,7 @@ export const formatStaticPayload = (
   image: Int16Array
 ) => {
   const fd = new FormData();
-  const metadata: TStaticImeasurePayload = {
+  const metadata: IStaticIMeasurePayload = {
     id: input.id,
     clicks: input.clicks,
     world_origin: vec3ToPoint3D(input.worldOrigin),

package/src/types/io.ts

@@ -1,5 +1,13 @@
 import { Point3D } from "./cornerstone";
 
+/**
+ * Represents a raw measurement between two points in both voxel and world spaces.
+ *
+ * @property coords_voxel - The start and end points of the measurement in voxel-space coordinates.
+ * @property coords_world - The start and end points of the measurement in world-space coordinates.
+ * @property length_voxel - The distance between the two points in voxel space.
+ * @property length_world - The distance between the two points in world space.
+ */
 export type TRawMeasurement = {
   coords_voxel: [Point3D, Point3D];
   coords_world: [Point3D, Point3D];
@@ -7,26 +15,115 @@ export type TRawMeasurement = {
   length_world: number;
 };
 
+/**
+ * Represents a cross measurement consisting of two raw measurements.
+ *
+ * @property short - The shorter measurement in the cross.
+ * @property long - The longer measurement in the cross.
+ */
 export type TCrossMeasurement = {
   short: TRawMeasurement;
   long: TRawMeasurement;
 };
 
-export type TIMeasure3DResponse = {
-  mask: string; // a base64-encoded string that represents the mask
-  measurements: {
-    cross: {
-      // TODO: make this an array
-      0: TCrossMeasurement;
-      1: TCrossMeasurement;
-      2: TCrossMeasurement; // this could be the only relevant one as it is in "axial" orientation
-    };
-    diagonal: TRawMeasurement;
-    height: TRawMeasurement;
+/**
+ * Represents a collection of measurements derived from the resulting segmentation mask.
+ *
+ * @property cross - Contains measurements for the cross section, with the key "2" representing the axial plane.
+ * @property diagonal - Represents the diagonal measurement.
+ * @property height - Represents the height measurement.
+ * @privateRemarks
+ * the key of "2" should be replaced with a more descriptive name in the future, eg. "axial"
+ */
+
+export type TMeasurements = {
+  cross: {
+    2: TCrossMeasurement;
   };
+  diagonal: TRawMeasurement;
+  height: TRawMeasurement;
 };
 
-// Shared generics
+/**
+ * The return type of the static IMeasure 3D API endpoint.
+ *
+ * @property mask - A base64-encoded string that represents the flattened 3D segmentation mask.
+ * The mask is a binary representation of the segmentation, with `0` representing background voxels and `1` representing foreground voxels.
+ * To marshal it into a 3D mask, the client should convert the base64 string into an array of numbers and reshape it
+ * to conform to the returned `mask_shape` property.
+ * @property measurements - An object containing cross, diagonal, and height measurements.
+ * @property volume_mm3 - The volume of the segmentation in cubic millimeters.
+ * @property volume - The volume of the segmentation in voxels.
+ * @property mask_shape - The shape of the mask in voxels, represented as a tuple of three integers (x, y, z).
+ * @property mask_spacing - The world-space spacing of the mask in voxel coordinates, represented as a tuple of three floats (x, y, z).
+ * @property mask_origin_voxel - The origin of the mask in voxel coordinates, represented as a tuple of three integers (x, y, z).
+ *
+ * @interface
+ */
+
+export type TIMeasure3DResponse = {
+  mask: string;
+  measurements: TMeasurements;
+  volume_mm3: number;
+  volume: number;
+  mask_shape: [number, number, number];
+  mask_spacing: Point3D;
+  mask_origin_voxel: Point3D;
+};
+
+/**
+ * The generic input type for the `metadata` part of an iMeasure request, expended by the default Static and experimental
+ * Interactive iMeasure variants.
+ *
+ * This type is used to define the metadata that is sent along with the iMeasure request and should be included
+ * in the multipart FormData request body as a `Blob`:
+ * ```typescript
+ * const formData = new FormData();
+ * formData.append("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }));
+ * ```
+ *
+ * @see the function {@link metadata.extractWorldMetaFromImageDataAndDisplaySet | extractWorldMetaFromImageDataAndDisplaySet} for deriving the following properties from a VTK volume and an OHIF displayset:
+ *   - * `worldOrigin`
+ *   - * `worldShape`
+ *   - * `worldSpacing`
+ *   - * `worldBoundingImagePositions`
+ *   - * `imageCount`
+ *   - * `rescaleIntercept`
+ *   - * `rescaleSlope`
+ *   - * `imageOrientationPatient`
+ * @see the function {@link math.cropping.calculateStaticImeasureBoundingBox | calculateStaticImeasureBoundingBox} in for deriving the following properties from user clicks and world affines:
+ *   - * `cropBoundariesWorld`
+ *   - * `cropBoundariesVoxel`
+ *   - * `cropBoundariesUnclippedVoxel`
+ *   - * `cropCuboidCenterVoxel`
+ *   - * `shape`
+ *
+ * @see the {@link formatting.formatStaticPayload | formatStaticPayload} function for an utility function for constructing the FormData
+ * payload from an union of {@link Types.Metadata.TWorldMetadata | TWorldMetadata}, {@link Types.Metadata.TCropMetadata | TCropMetadata} and parsed image data.
+ *
+ * @property id - A unique UUID4-compliant identifier for the measurement.
+ * @property world_origin - The origin of the world coordinate system in world-space, represented as a tuple of three floats (x, y, z).
+ * @property world_shape - The shape of the world voxel space, represented as a tuple of three integers (x, y, z) - eg. [512, 512, 100].
+ * @property world_spacing - The spacing of the world voxel space, represented as a tuple of three floats (x, y, z).
+ * @property rescale_intercept - The rescale intercept value for the underlying series, used to adjust/normalize pixel values.
+ * @property rescale_slope - The rescale slope value for the underlying series, used to adjust/normalize pixel values.
+ * @property image_orientation_patient - The image orientation in patient coordinates, represented as a tuple of six floats
+ * (x1, y1, z1, x2, y2, z2), where (x1, y1, z1) and (x2, y2, z2) are the direction cosines of the image axes.
+ * @property crop_boundaries_world - The boundaries of the crop region in world coordinates, represented as a tuple of two Point3D objects
+ * (minPoint, maxPoint), where minPoint and maxPoint are the minimum and maximum points of the crop region in world space.
+ * @property crop_boundaries_voxel - The boundaries of the crop region in voxel coordinates, represented as a tuple of two Point3D objects
+ * (minPoint, maxPoint), where minPoint and maxPoint are the minimum and maximum points of the crop region in voxel space.
+ * @property crop_boundaries_unclipped_voxel - The unclipped boundaries of the crop region in voxel coordinates,
+ * represented as a tuple of two Point3D objects (minPoint, maxPoint),
+ * where minPoint and maxPoint are the minimum and maximum points of the crop region in voxel space before clipping.
+ * @property crop_cuboid_center_voxel - The center of the crop cuboid in voxel coordinates, represented as a
+ * Point3D object (x, y, z), where (x, y, z) are the coordinates of the center point of the crop cuboid in voxel space before clipping.
+ * @property shape - The shape of the cropped volume, represented as a tuple of three integers (x, y, z).
+ * @property world_bounding_image_positions - Effectively the ImagePositionPatient values for the first and last images in the series,
+ * represented as a tuple of two Point3D objects (firstPosition, lastPosition).
+ * @property image_count - The number of images in the entire series.
+ */
+
 export type TIMeasure3DGenericPayload = {
   id: string;
   world_origin: Point3D;
@@ -44,18 +141,40 @@ export type TIMeasure3DGenericPayload = {
   image_count: number;
 };
 
-export type TStaticImeasurePayload = TIMeasure3DGenericPayload & {
+/**
+ * The shape of the payload for static iMeasure operations.
+ *
+ * @remarks
+ * This type extends {@link TIMeasure3DGenericPayload}, inheriting all its properties,
+ * and adds a `clicks` property representing two 3D points.
+ *
+ * @property clicks - A tuple containing two {@link Point3D} objects, representing the selected points in 3D space.
+ *
+ * @see {@link TIMeasure3DGenericPayload} for inherited properties and additional context.
+ */
+export interface IStaticIMeasurePayload extends TIMeasure3DGenericPayload {
   clicks: [Point3D, Point3D];
-};
+}
+
+// TODO: better docs from this point onwards - marked as internal for now to not include
+// them in the docs.
 
-// interactive input and payload types
+/**
+ * @internal
+ */
 export type TInteractiveIMeasureMode = "positive" | "negative";
+/**
+ * @internal
+ */
 export type TInteractiveIMeasureModeClicks = {
   mode: TInteractiveIMeasureMode;
   points: Point3D[];
   firstClick?: true;
 };
 
+/**
+ * @internal
+ */
 export type TInteractiveImeasurePayload = TIMeasure3DGenericPayload & {
   finding_id?: string;
   clicks: TInteractiveIMeasureModeClicks[];