@opentrons/shared-data 0.1.7-alpha.1 → 0.2.0-alpha.0

package/lib/js/helpers/positionMath.d.ts

@@ -0,0 +1,127 @@
+/** Compute positions of labware stacked upon other labware, modules, deck slots, etc. */
+import type { AddressableArea, DeckDefinition, LabwareDefinition, LabwareDefinition2, ModuleDefinition, Vector3D } from '../types';
+/** Return dimensions of the total labware bounding box in the style of labware schema 2. */
+export declare function getSchema2Dimensions(definition: LabwareDefinition): LabwareDefinition2['dimensions'];
+/**
+ * Return a bounding box, in coordinates relative to the labware's origin,
+ * that encloses the labware when viewed from the top down.
+ */
+export declare function getLabwareViewBox(definition: LabwareDefinition): {
+    /** The minimum x-coord, i.e. the left of the labware. */
+    minX: number;
+    /** The minimum y-coord, i.e. the front of the labware. */
+    minY: number;
+    /** The maximum x-coord, i.e. the right of the labware. */
+    maxX: number;
+    /** The maximum y-coord, i.e. the back of the labware. */
+    maxY: number;
+    /** The distance between left and right. */
+    xDimension: number;
+    /** The distance between front and back. */
+    yDimension: number;
+};
+/** Logically specifies where a labware is located. */
+export interface ComputeLabwareOriginInput {
+    /** The underlying deck. */
+    deckDefinition: DeckDefinition;
+    /**
+     * The underlying slot. If this is a Flex and the labware is on a module, this should
+     * be the slot that the module replaces.
+     */
+    slotId: string;
+    /**
+     * The definition of the module underneath the labware, if there is one.
+     * This should be specified even if it's only transitively underneath the labware,
+     * like slot -> module -> adapter -> labware in question.
+     */
+    moduleDefinition: ModuleDefinition | null;
+    /** The labware and all the labware underneath it. */
+    labwareDefinitionsBottomToTop: LabwareDefinition[];
+}
+/**
+ * Computes the absolute deck coordinates of a labware.
+ * Returns null if there was some internal error.
+ */
+export declare function computeLabwareOrigin(input: ComputeLabwareOriginInput): Vector3D | null;
+/**
+ * Return the offset from a deck slot's origin (the slot's front-left, -x, -y)
+ * to a labware's origin (varies depending on the labware),
+ * supposing the labware is placed in that slot.
+ */
+export declare function getDeckSlotOriginToLabwareOrigin(slotDefinition: AddressableArea, labwareDefinition: LabwareDefinition): Vector3D;
+/**
+ * Given a stackup like:
+ *
+ * deck slot --> module --> labware
+ *
+ * This computes the offset from the deck slot's origin (its front-left / -x,-y corner)
+ * to the labware's origin (varies depending on the labware).
+ *
+ * This is currently how it works even for Flex modules, even though they are not really
+ * "in a slot." The slot in this case is the slot that the module replaces.
+ *
+ * The API is like this for transitional reasons. Ideally, we would have one function
+ * to go slot->module and a second function to go module->labware.
+ */
+export declare function getModuleParentOriginToLabwareOrigin(deckId: string, slotId: string | null, moduleDefinition: ModuleDefinition, labwareDefinition: LabwareDefinition): Vector3D;
+/**
+ * Given a labware -> labware stackup, compute the offset from the parent (bottom)
+ * labware's origin to the child (top) labware's origin.
+ */
+export declare function getLabwareOriginToLabwareOrigin(parentDefinition: LabwareDefinition, childDefinition: LabwareDefinition): Vector3D;
+/**
+ * Given a module, computes the offset from the origin (front-left, -x,-y corner) of the
+ * deck slot that the module is in, to the origin (again, front-left, -x,-y corner) of
+ * the slot atop that module.
+ *
+ * On a Flex, modules are not really "in deck slots". There, "the deck slot that the
+ * module is in" means "the deck slot that the module replaces."
+ *
+ * @deprecated We are trying to move away from the idea that modules always have slots
+ *  atop them and that things should be positioned relative to those slots' -x,-y
+ *  corners. That idea is especially untrue for things like the Thermocycler and
+ *  Heater-Shaker. You probably want `getModuleParentOriginToLabwareOrigin()` instead,
+ *  which is higher-level and can model different ways that a labware can mate with a
+ *  module. This is exported to support things like UI controls that want to cover
+ *  a module's "labware area" and whose implementations assume the traditional
+ *  slot -x,-y corner idea.
+ */
+export declare function getModuleParentOriginToChildSlotOrigin(deckId: string, slotId: string | null, moduleDefinition: ModuleDefinition): Vector3D;
+/**
+ * Return the offset from a labware's back-left-bottom (-x, +y, -z) corner to its origin.
+ *
+ * This is a lower-level helper for the rare cases where we want to position a labware
+ * specifically by its back-left corner. Typically, you'll want something higher-level,
+ * like `getLabwareViewBox()` or `getDeckSlotOriginToLabwareOrigin()`, instead.
+ */
+export declare function getLabwareBackLeftBottomToOrigin(definition: LabwareDefinition): Vector3D;
+/**
+ * Return a definition's cornerOffsetFromSlot in the style of labware schema 2.
+ *
+ * @deprecated This is probably an inherently wrong interface to attempt, for a couple
+ * reasons.
+ *
+ * FIRST, depending on what the call site does with this, it might expect the return
+ * value to be either:
+ *
+ * - The vector from the (-x, -y) corner of the parent slot to the (-x, -y) corner of
+ *   the labware
+ * - The vector from the (-x, -y) corner of the parent slot to the origin of the
+ *   labware
+ *
+ * In labware schema 2, these were the same thing, but not in schema 3.
+ *
+ * SECOND, in labware schema 2, how a child labware sits on its parent is almost
+ * entirely a function of the child's definition. In labware schema 3, it is
+ * much more dependent on information only available in the parent. For example, to
+ * line up a child's well A1 with a parent's well A1, we need to know where the
+ * parent's well A1 is. (Schema 2 just did not attempt to support that).
+ *
+ * For schema-2 definitions, this will return cornerOffsetFromSlot as-is.
+ *
+ * For schema-3 definitions, this currently returns the placeholder (12, 34, 56), which
+ * is certainly wrong and will cause all manner of visual mayhem, but at least it's
+ * wrong in an obvious way and it unblocks importing schema-3 definitions. Solving this
+ * properly is call-site-dependent, as described above.
+ */
+export declare function getSchema2CornerOffsetFromSlot(definition: LabwareDefinition): LabwareDefinition2['cornerOffsetFromSlot'];

package/lib/js/helpers/validateCustomLabwareHelper.d.ts

@@ -1,4 +1,4 @@
-import type { LabwareDefinition2 } from '..';
+import type { LabwareDefinition } from '..';
 /**
  * This function is used to help validate that the wells and ordering matches in
  * a custom labware definition in terms of the wellName and the wells length
@@ -6,4 +6,4 @@ import type { LabwareDefinition2 } from '..';
  * @param definition - a labware definition
  * @returns A boolean for if they exist
  */
-export declare const validateCustomLabwareHelper: (definition?: LabwareDefinition2 | null) => boolean;
+export declare const validateCustomLabwareHelper: (definition?: LabwareDefinition | null) => boolean;

package/lib/js/helpers/vectorMath.d.ts

@@ -0,0 +1,14 @@
+import type { CoordinateTuple, Vector3D } from '../types';
+export declare const IDENTITY_VECTOR: Vector3D;
+/**
+ * Add an arbitrary number of vectors.
+ * e.g. `getVectorSum(a, b, c)` is a + b + c.
+ */
+export declare function getVectorSum(first: Vector3D, ...rest: Vector3D[]): Vector3D;
+/**
+ * Subtract an arbitrary number of vectors.
+ * e.g. `getVectorDifference(a, b, c)` is a - b - c.
+ */
+export declare function getVectorDifference(first: Vector3D, ...rest: Vector3D[]): Vector3D;
+export declare function getVectorInverse(vector: Vector3D): Vector3D;
+export declare function coordinateTupleToVector3D(coordinateTuple: CoordinateTuple): Vector3D;

package/lib/js/helpers/wellSets.d.ts

@@ -1,17 +1,17 @@
-import type { LabwareDefinition2, NozzleLayoutConfig, PipetteV2Specs } from '../types';
+import type { LabwareDefinition, NozzleLayoutConfig, PipetteV2Specs } from '../types';
 type WellSetByPrimaryWell = string[][];
 export interface NozzleLayoutDetails {
     nozzleConfig: NozzleLayoutConfig;
     activeNozzleCount: number;
 }
 export interface WellSetForMultiChannelParams {
-    labwareDef: LabwareDefinition2;
+    labwareDef: LabwareDefinition;
     wellName: string;
     channels: 8 | 96;
     pipetteNozzleDetails?: NozzleLayoutDetails;
 }
 export interface WellSetHelpers {
-    getAllWellSetsForLabware: (labwareDef: LabwareDefinition2) => WellSetByPrimaryWell;
+    getAllWellSetsForLabware: (labwareDef: LabwareDefinition) => WellSetByPrimaryWell;
     /** Given a well for a labware, returns the well set it belongs to (or null)
      * for 8-channel and 96-channel access.
      * Ex: C2 for 96-flat => ['A2', 'B2', 'C2', ... 'H2']
@@ -21,7 +21,7 @@ export interface WellSetHelpers {
      * nozzle configuration.
      **/
     getWellSetForMultichannel: (params: WellSetForMultiChannelParams) => string[] | null | undefined;
-    canPipetteUseLabware: (pipetteSpec: PipetteV2Specs, labwareDef?: LabwareDefinition2, trashName?: string) => boolean;
+    canPipetteUseLabware: (pipetteSpec: PipetteV2Specs, labwareDef?: LabwareDefinition, trashName?: string) => boolean;
 }
 export declare const makeWellSetHelpers: () => WellSetHelpers;
 export {};

package/lib/js/labware.d.ts

@@ -9,11 +9,12 @@ import fixtureTiprack10ul from '../labware/fixtures/2/fixture_tiprack_10_ul.json
 import fixtureTiprack300ul from '../labware/fixtures/2/fixture_tiprack_300_ul.json';
 import fixtureTrash from '../labware/fixtures/2/fixture_trash.json';
 import labwareSchemaV2 from '../labware/schemas/2.json';
-import type { LabwareDefByDefURI, LabwareDefinition2, LegacyLabwareDefByName } from './types';
+import labwareSchemaV3 from '../labware/schemas/3.json';
+import type { LabwareDef2ByDefURI, LabwareDefinition2, LegacyLabwareDefByName } from './types';
 export declare const getAllLabwareDefs: () => Record<string, LabwareDefinition2>;
-export declare function getAllDefinitions(blockList?: string[]): LabwareDefByDefURI;
+export declare function getAllDefinitions(blockList?: string[]): LabwareDef2ByDefURI;
 export declare function getAllLegacyDefinitions(): LegacyLabwareDefByName;
-export { labwareSchemaV2, fixture96Plate, fixture12Trough, fixture24Tuberack, fixtureTiprack10ul, fixtureTiprack300ul, fixtureTiprack1000ul, fixtureTiprackAdapter, fixtureTrash, fixture384Plate, fixtureCalibrationBlock, };
+export { labwareSchemaV2, labwareSchemaV3, fixture96Plate, fixture12Trough, fixture24Tuberack, fixtureTiprack10ul, fixtureTiprack300ul, fixtureTiprack1000ul, fixtureTiprackAdapter, fixtureTrash, fixture384Plate, fixtureCalibrationBlock, };
 export declare const opentrons96PcrAdapterV1: LabwareDefinition2;
 export declare const opentrons1Trash3200MlFixedV1: LabwareDefinition2;
 export declare const opentrons96Tiprack10UlV1Uncasted: LabwareDefinition2;

package/lib/js/liquidClasses.d.ts

@@ -1,2 +1,6 @@
 import type { LiquidClass } from '.';
+export declare const WATER_LIQUID_CLASS_NAME = "waterV1";
+export declare const NONE_LIQUID_CLASS_NAME = "none";
+export declare const GLYCEROL_LIQUID_CLASS_NAME = "glycerol50V1";
+export declare const ETHANOL_LIQUID_CLASS_NAME = "ethanol80V1";
 export declare const getAllLiquidClassDefs: () => Record<string, LiquidClass>;

package/lib/js/modules.d.ts

@@ -1,5 +1,5 @@
 import type { ModuleDefinition, ModuleModel, ModuleModelWithLegacy, ModuleType } from './types';
-export declare const getModuleDef2: (moduleModel: ModuleModel) => ModuleDefinition;
+export declare const getModuleDef: (moduleModel: ModuleModel) => ModuleDefinition;
 export declare function normalizeModuleModel(legacyModule: ModuleModelWithLegacy): ModuleModel;
 export declare function getModuleType(moduleModel: ModuleModel): ModuleType;
 export declare function getModuleDisplayName(moduleModel: ModuleModel): string;

package/lib/js/types.d.ts

@@ -1,7 +1,7 @@
 import type { LoadedLabwareLocation, RunTimeCommand } from '../command/types';
 import type { CommandAnnotation } from '../commandAnnotation/types';
 import type { AddressableAreaName, CutoutFixtureId, CutoutId } from '../deck';
-import type { ABSORBANCE_READER_TYPE, ABSORBANCE_READER_V1, EXTENSION, FLEX, FLEX_STACKER_MODULE_TYPE, FLEX_STACKER_MODULE_V1, GEN1, GEN2, GRIPPER_V1, GRIPPER_V1_1, GRIPPER_V1_2, GRIPPER_V1_3, HEATERSHAKER_MODULE_TYPE, HEATERSHAKER_MODULE_V1, LEFT, MAGDECK, MAGNETIC_BLOCK_TYPE, MAGNETIC_BLOCK_V1, MAGNETIC_MODULE_TYPE, MAGNETIC_MODULE_V1, MAGNETIC_MODULE_V2, POSITION_REFERENCE_BOTTOM, POSITION_REFERENCE_CENTER, POSITION_REFERENCE_LIQUID_MENISCUS, POSITION_REFERENCE_TOP, RIGHT, TEMPDECK, TEMPERATURE_MODULE_TYPE, TEMPERATURE_MODULE_V1, TEMPERATURE_MODULE_V2, THERMOCYCLER, THERMOCYCLER_MODULE_TYPE, THERMOCYCLER_MODULE_V1, THERMOCYCLER_MODULE_V2 } from './constants';
+import type { ABSORBANCE_READER_TYPE, ABSORBANCE_READER_V1, AddressableAreaNamesWithFakes, AddressableAreaWithFakes, AreaTypeWithFakes, CutoutFixtureIdsWithFakes, EXTENSION, FLEX, FLEX_STACKER_MODULE_TYPE, FLEX_STACKER_MODULE_V1, GEN1, GEN2, GRIPPER_V1, GRIPPER_V1_1, GRIPPER_V1_2, GRIPPER_V1_3, HEATERSHAKER_MODULE_TYPE, HEATERSHAKER_MODULE_V1, LEFT, MAGDECK, MAGNETIC_BLOCK_TYPE, MAGNETIC_BLOCK_V1, MAGNETIC_MODULE_TYPE, MAGNETIC_MODULE_V1, MAGNETIC_MODULE_V2, POSITION_REFERENCE_BOTTOM, POSITION_REFERENCE_CENTER, POSITION_REFERENCE_LIQUID_MENISCUS, POSITION_REFERENCE_TOP, RIGHT, TEMPDECK, TEMPERATURE_MODULE_TYPE, TEMPERATURE_MODULE_V1, TEMPERATURE_MODULE_V2, THERMOCYCLER, THERMOCYCLER_MODULE_TYPE, THERMOCYCLER_MODULE_V1, THERMOCYCLER_MODULE_V2 } from './constants';
 import type { PipetteName } from './pipettes';
 export type RobotType = 'OT-2 Standard' | 'OT-3 Standard';
 export interface RobotDefinition {
@@ -137,9 +137,16 @@ export interface RoundedCuboidSegment {
     bottomHeight: number;
 }
 export type WellSegment = CuboidalFrustum | ConicalFrustum | SquaredConeSegment | SphericalSegment | RoundedCuboidSegment;
+export interface HeightVolumePair {
+    height: number;
+    volume: number;
+}
 export interface InnerWellGeometry {
     sections: WellSegment[];
 }
+export interface UserDefinedVolumes {
+    heightToVolumeMap: HeightVolumePair[];
+}
 export type LabwareWellMap = Record<string, LabwareWell>;
 export interface LabwareWellGroupMetadata {
     displayName?: string;
@@ -161,7 +168,20 @@ export interface AxisAlignedBoundingBox3D {
 }
 export interface Extents {
     total: AxisAlignedBoundingBox3D;
-    footprint: AxisAlignedBoundingBox2D;
+}
+export interface SlotFootprintAsChildFeature {
+    z: number;
+    backLeft: Vector2D;
+    frontRight: Vector2D;
+}
+export interface SlotFootprintAsParentFeature {
+    z: number;
+    backLeft: Vector2D;
+    frontRight: Vector2D;
+}
+export interface LocatingFeatures {
+    slotFootprintAsChild?: SlotFootprintAsChildFeature;
+    slotFootprintAsParent?: SlotFootprintAsParentFeature;
 }
 export type LabwareRoles = 'labware' | 'adapter' | 'fixture' | 'maintenance' | 'lid' | 'system';
 export interface LabwareDefinition2 {
@@ -181,7 +201,7 @@ export interface LabwareDefinition2 {
     stackingOffsetWithModule?: Record<string, LabwareOffset>;
     stackLimit?: number;
     compatibleParentLabware?: string[];
-    innerLabwareGeometry?: Record<string, InnerWellGeometry> | null;
+    innerLabwareGeometry?: Record<string, InnerWellGeometry | UserDefinedVolumes> | null;
 }
 export interface LabwareDefinition3 {
     version: number;
@@ -190,6 +210,7 @@ export interface LabwareDefinition3 {
     namespace: string;
     metadata: LabwareMetadata;
     extents: Extents;
+    features: LocatingFeatures;
     parameters: LabwareParameters;
     brand: LabwareBrand;
     ordering: string[][];
@@ -202,7 +223,8 @@ export interface LabwareDefinition3 {
     compatibleParentLabware?: string[];
     innerLabwareGeometry?: Record<string, InnerWellGeometry> | null;
 }
-export interface LabwareDefByDefURI {
+export type LabwareDefinition = LabwareDefinition2 | LabwareDefinition3;
+export interface LabwareDef2ByDefURI {
     [defUri: string]: LabwareDefinition2;
 }
 export interface LegacyLabwareDefByName {
@@ -244,10 +266,11 @@ export interface DeckCalibrationPoint {
     position: CoordinateTuple;
     displayName: string;
 }
+export type CutoutIdToCutoutFixtureId = {
+    [cutoutId in CutoutId]?: CutoutFixtureId;
+};
 export type CutoutFixtureGroup = {
-    [cutoutId in CutoutId]?: Array<{
-        [cutoutId in CutoutId]?: CutoutFixtureId;
-    }>;
+    [cutoutId in CutoutId]?: CutoutIdToCutoutFixtureId[];
 };
 export interface CutoutFixture {
     id: CutoutFixtureId;
@@ -258,7 +281,12 @@ export interface CutoutFixture {
     fixtureGroup: CutoutFixtureGroup;
     height: number;
 }
-type AreaType = 'slot' | 'movableTrash' | 'wasteChute' | 'fixedTrash' | 'stagingSlot' | 'lidDock';
+export interface FakeCutoutFixture extends Omit<CutoutFixture, 'id' | 'providesAddressableAreas'> {
+    id: CutoutFixtureIdsWithFakes;
+    providesAddressableAreas: Record<CutoutId, AddressableAreaNamesWithFakes[] | AddressableAreaName[]>;
+}
+export type CutoutFixtureWithFakes = FakeCutoutFixture | CutoutFixture;
+export type AreaType = 'slot' | 'movableTrash' | 'wasteChute' | 'fixedTrash' | 'stagingSlot' | 'lidDock' | 'thermocycler' | 'heaterShaker' | 'temperatureModule' | 'magneticBlock' | 'absorbanceReader' | 'flexStacker';
 export interface AddressableArea {
     id: AddressableAreaName;
     areaType: AreaType;
@@ -270,6 +298,10 @@ export interface AddressableArea {
     ableToDropTips?: boolean;
     matingSurfaceUnitVector?: UnitVectorTuple;
 }
+export interface FakeAddressableArea extends Omit<AddressableArea, 'id' | 'areaType'> {
+    id: AddressableAreaNamesWithFakes;
+    areaType: AreaTypeWithFakes;
+}
 export interface DeckMetadata {
     displayName: string;
     tags: string[];
@@ -291,6 +323,9 @@ export interface DeckLocations {
     cutouts: DeckCutout[];
     legacyFixtures: LegacyFixture[];
 }
+export interface DeckLocationsWithFakes extends Omit<DeckLocations, 'addressableAreas' | 'calibrationPoints' | 'legacyFixtures'> {
+    addressableAreas: AddressableAreaWithFakes[];
+}
 export interface DeckDefinition {
     otId: string;
     cornerOffsetFromOrigin: CoordinateTuple;
@@ -300,6 +335,10 @@ export interface DeckDefinition {
     metadata: DeckMetadata;
     cutoutFixtures: CutoutFixture[];
 }
+export interface DeckDefinitionWithFakes extends Omit<DeckDefinition, 'locations' | 'cutoutFixtures' | 'otId' | 'cornerOffsetFromOrigin' | 'dimensions' | 'metadata' | 'robot'> {
+    locations: DeckLocationsWithFakes;
+    cutoutFixtures: CutoutFixtureWithFakes[];
+}
 export interface ModuleDimensions {
     bareOverallHeight: number;
     overLabwareHeight: number;
@@ -331,12 +370,17 @@ export interface ModuleDefinition {
     quirks: string[];
     slotTransforms: SlotTransforms;
     compatibleWith: ModuleModel[];
-    twoDimensionalRendering: any;
 }
-export type AffineTransformMatrix = number[][];
+type AffineTransformRow = [number, number, number, number];
+export type AffineTransformMatrix = [
+    AffineTransformRow,
+    AffineTransformRow,
+    AffineTransformRow,
+    AffineTransformRow
+];
 export interface SlotTransforms {
-    [deckOtId: string]: {
-        [slotId: string]: {
+    [deckOtId: string]: undefined | {
+        [slotId: string]: undefined | {
             [transformKey in keyof ModuleDefinition]?: AffineTransformMatrix;
         };
     };
@@ -636,7 +680,7 @@ export interface ByTipTypeSetting {
     singleDispense: SingleDispenseProperties;
     multiDispense?: MultiDispenseProperties;
 }
-interface ByPipetteSetting {
+export interface ByPipetteSetting {
     pipetteModel: string;
     byTipType: ByTipTypeSetting[];
 }
@@ -796,5 +840,10 @@ export interface CutoutConfig {
     opentronsModuleSerialNumber?: string;
 }
 export type DeckConfiguration = CutoutConfig[];
+type CutoutConfigWithoutCutoutFixtureId = Omit<CutoutConfig, 'cutoutFixtureId'>;
+export interface CutoutConfigMap extends CutoutConfigWithoutCutoutFixtureId {
+    addressableAreaId: AddressableAreaNamesWithFakes;
+    cutoutFixtureId: CutoutFixtureIdsWithFakes;
+}
 export type NozzleLayoutConfig = 'single' | 'column' | 'row' | 'full' | 'subrect';
 export {};