@zaber/motion 8.4.0 → 9.0.0

package/dist/lib/ascii/pvt_sequence.js

@@ -28,7 +28,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PvtSequence = void 0;
 const gateway = __importStar(require("../gateway"));
 const requests = __importStar(require("../requests"));
-const pvt_sequence_data_1 = require("./pvt_sequence_data");
+const pvt_partial_csv_data_1 = require("./pvt_partial_csv_data");
 const pvt_csv_data_1 = require("./pvt_csv_data");
 const pvt_io_1 = require("./pvt_io");
 /**
@@ -124,7 +124,7 @@ class PvtSequence {
             device: this.device.deviceAddress,
             streamId: this.pvtId,
             pvt: true,
-            pvtBuffer: pvtBuffer.bufferId,
+            pvtBuffer: pvtBuffer.bufferNumber,
             pvtAxes: pvtAxes,
             toBinary() {
                 return requests.StreamSetupStoreCompositeRequest.toBinary(this);
@@ -135,7 +135,7 @@ class PvtSequence {
     /**
      * Setup the PVT sequence to use the specified axes and queue actions into a PVT buffer.
      * @param pvtBuffer The PVT buffer to queue actions in.
-     * @param axes Numbers of physical axes to setup the PVT sequence on.
+     * @param axes The axis numbers of the physical axes to setup the PVT sequence on.
      */
     async setupStore(pvtBuffer, ...axes) {
         const request = {
@@ -144,7 +144,7 @@ class PvtSequence {
             device: this.device.deviceAddress,
             streamId: this.pvtId,
             pvt: true,
-            pvtBuffer: pvtBuffer.bufferId,
+            pvtBuffer: pvtBuffer.bufferNumber,
             axes: axes,
             toBinary() {
                 return requests.StreamSetupStoreRequest.toBinary(this);
@@ -163,7 +163,7 @@ class PvtSequence {
             device: this.device.deviceAddress,
             streamId: this.pvtId,
             pvt: true,
-            pvtBuffer: pvtBuffer.bufferId,
+            pvtBuffer: pvtBuffer.bufferNumber,
             toBinary() {
                 return requests.StreamCallRequest.toBinary(this);
             },
@@ -174,6 +174,8 @@ class PvtSequence {
      * Queues a point with absolute coordinates in the PVT sequence.
      * If some or all velocities are not provided, the sequence calculates the velocities
      * from surrounding points using finite difference.
+     * If time value is zero, the device must already be idle at the specified position
+     * and the specified velocity must be zero.
      * The last point of the sequence must have defined velocity (likely zero).
      * @param positions Positions for the axes to move through, relative to their home positions.
      * @param velocities The axes velocities at the given point.
@@ -198,7 +200,15 @@ class PvtSequence {
         await gateway.callAsync('device/stream_point', request);
     }
     /**
+     * @deprecated This method is being replaced by the new SubmitSequenceData method.
+     *
      * Queues points with absolute coordinates in the PVT sequence.
+     * Each point must have its time value measured relative to the previous point
+     * or unexpected behavior will result.
+     *
+     * Note that if the first time value is zero, the device must already be idle at
+     * the position of the first point and the velocity of that point must be zero.
+     * All other time values must be greater than zero.
      * @param positions Per-axis sequences of positions.
      * @param velocities Per-axis sequences of velocities.
      * For velocities [v0, v1, ...] and positions [p0, p1, ...], v1 is the target velocity at point p1.
@@ -226,6 +236,10 @@ class PvtSequence {
      * Queues a point with coordinates relative to the previous point in the PVT sequence.
      * If some or all velocities are not provided, the sequence calculates the velocities
      * from surrounding points using finite difference.
+     *
+     * The time value must be greater than zero, and each point must have its time value
+     * measured relative to the previous point or unexpected behavior will result.
+     *
      * The last point of the sequence must have defined velocity (likely zero).
      * @param positions Positions for the axes to move through, relative to the previous point.
      * @param velocities The axes velocities at the given point.
@@ -250,7 +264,11 @@ class PvtSequence {
         await gateway.callAsync('device/stream_point', request);
     }
     /**
+     * @deprecated This method is being replaced by the new SubmitSequenceData method.
+     *
      * Queues points with coordinates relative to the previous point in the PVT sequence.
+     * All time values must be greater than zero and each point must have its time value
+     * measured relative to the previous point or unexpected behavior will result.
      * @param positions Per-axis sequences of positions.
      * @param velocities Per-axis sequences of velocities.
      * For velocities [v0, v1, ...] and positions [p0, p1, ...], v1 is the target velocity at point p1.
@@ -279,68 +297,56 @@ class PvtSequence {
      * of velocities. Note that if some velocities are defined, the solver will NOT modify them in any way.
      * If all velocities are defined, the solver will simply return the same velocities.
      * This function calculates velocities by enforcing that acceleration be continuous at each segment transition.
+     * The function does not modify the input positions or times.
      *
-     * Also note that if generating a path for multiple axes, the user must provide a position measurement sequence
-     * per axis, And the values arrays for each sequence must be equal in length to each other and also to the
-     * times sequence.
+     * Also note that if the first position is relative, all following points must be relative.
+     * If the start position is absolute, then the sequence can include a mix of relative and absolute positions.
+     * Additionally, all times must be relative to the previous point.
+     * Please see the ConvertTimeAbsoluteToRelativePartial function for conversions.
      *
      * Does not support native units.
-     * @param positions Positions for the axes to move through, relative to their home positions.
-     * Each MeasurementSequence represents a sequence of positions along a particular dimension.
-     * For example, a 2D path sequence would contain two MeasurementSequence objects,
-     * one representing positions along X and one for those along Y.
-     * @param times The relative or absolute time of each position in the PVT sequence.
-     * @param velocities Optional velocities corresponding to each point in the position sequences.
-     * @param [timesRelative=true] If true, the times sequence values are interpreted as relative. Otherwise,
-     * they are interpreted as absolute. Note that the values of the returned time
-     * sequence are ALWAYS relative. This is because the PVT sequence API expects
-     * points to have relative times.
-     * @returns Object containing the generated PVT sequence. Note that returned time sequence is always relative.
-     */
-    static async generateVelocities(positions, times, velocities, timesRelative = true) {
+     * @param sequenceItems Partial PVT points defining the positions, optional velocities, and times for the sequence.
+     * Each point should have positions defined for each axis. Velocities are optional.
+     * Times must be defined for each point.
+     * @returns Array of points and actions containing the generated PVT sequence. Note returned times are always relative.
+     */
+    static async generateVelocities(sequenceItems) {
         const request = {
             ...requests.PvtGenerateVelocitiesRequest.DEFAULT,
-            positions: positions,
-            times: times,
-            velocities: velocities,
-            timesRelative: timesRelative,
+            sequenceItems: sequenceItems,
             toBinary() {
                 return requests.PvtGenerateVelocitiesRequest.toBinary(this);
             },
         };
-        const response = await gateway.callAsync('device/pvt_generate_velocities', request, pvt_sequence_data_1.PvtSequenceData.fromBinary);
-        return response;
+        const response = await gateway.callAsync('device/pvt_generate_velocities', request, requests.PvtGenerateSequenceResponse.fromBinary);
+        return response.sequenceData;
     }
     /**
      * Generates positions for a sequence of velocities and times. This function calculates
      * positions by enforcing that acceleration be continuous at each segment transition.
      *
-     * Note that if generating a path for multiple axes, the user must provide a
-     * velocity measurement sequence per axis, and the values arrays for each sequence
-     * must be equal in length to each other and also to the times sequence.
+     * This function does not modify the input velocities or times, and outputs absolute
+     * positions. If your initial point has a time of zero, it will be considered a starting
+     * position when submitted to the device, and you must already have moved the device
+     * to that position. Additionally, all times must be relative to the previous point.
+     * Please see the ConvertTimeAbsoluteToRelativePartial function for conversions.
      *
      * Does not support native units.
-     * @param velocities The sequence of velocities for each axis.
-     * Each MeasurementSequence represents a sequence of velocities along particular dimension.
-     * @param times The relative or absolute time of each position in the PVT sequence.
-     * @param [timesRelative=true] If true, the times sequence values are interpreted as relative. Otherwise,
-     * they are interpreted as absolute. Note that the values of the returned time
-     * sequence are ALWAYS relative. This is because the PVT sequence API expects
-     * points to have relative times.
-     * @returns Object containing the generated PVT sequence. Note that returned time sequence is always relative.
+     * @param sequenceItems Partial PVT points defining the velocities and times for the sequence.
+     * Each point should have velocities defined for each axis.
+     * Times must be defined for each point.
+     * @returns Array of points and actions containing the generated PVT sequence. Note returned times are always relative.
      */
-    static async generatePositions(velocities, times, timesRelative = true) {
+    static async generatePositions(sequenceItems) {
         const request = {
             ...requests.PvtGeneratePositionsRequest.DEFAULT,
-            velocities: velocities,
-            times: times,
-            timesRelative: timesRelative,
+            sequenceItems: sequenceItems,
             toBinary() {
                 return requests.PvtGeneratePositionsRequest.toBinary(this);
             },
         };
-        const response = await gateway.callAsync('device/pvt_generate_positions', request, pvt_sequence_data_1.PvtSequenceData.fromBinary);
-        return response;
+        const response = await gateway.callAsync('device/pvt_generate_positions', request, requests.PvtGenerateSequenceResponse.fromBinary);
+        return response.sequenceData;
     }
     /**
      * Generates sequences of velocities and times for a sequence of positions.
@@ -358,22 +364,32 @@ class PvtSequence {
      * have no geometric significance without additional time information. Also note that
      * for multi-dimensional paths this function expects axes to be linear and orthogonal,
      * however for paths of a single dimension rotary units are accepted.
+     * Additionally, if the first positions of the input sequence is relative,
+     * all following positions must also be relative. If the first position is absolute,
+     * the sequence may contain a mix of relative and absolute positions.
+     * Resampling a sequence which contains relative positions is not allowed.
+     *
+     * This function outputs points with absolute positions and relative times, with the
+     * first time equal to zero, meaning it will be treated as a start position when
+     * executing on a device. You must move the device to that position before submitting
+     * the sequence, or change the first point's time to a value greater than zero.
      *
      * Does not support native units.
-     * @param positions Positions for the axes to move through, relative to their home positions.
+     * @param sequenceItems Partial PVT points defining the positions for the sequence.
+     * Each point should have positions defined for each axis.
      * @param targetSpeed The target speed used to generate positions and times.
      * @param targetAcceleration The target acceleration used to generate positions and times.
      * @param resampleNumber The number of points to resample the sequence by.
      * Leave undefined to use the specified points.
-     * @returns Object containing the generated PVT sequence. Note that returned time sequence is always relative.
+     * @returns Array of points and actions containing the generated PVT sequence. Note returned times are always relative.
      */
-    static async generateVelocitiesAndTimes(positions, targetSpeed, targetAcceleration, resampleNumber) {
+    static async generateVelocitiesAndTimes(sequenceItems, targetSpeed, targetAcceleration, resampleNumber) {
         if (targetSpeed.value <= 0 || targetAcceleration.value <= 0) {
             throw new TypeError('Target speed and acceleration values must be greater than zero.');
         }
         const request = {
             ...requests.PvtGenerateVelocitiesAndTimesRequest.DEFAULT,
-            positions: positions,
+            sequenceItems: sequenceItems,
             targetSpeed: targetSpeed,
             targetAcceleration: targetAcceleration,
             resampleNumber: resampleNumber,
@@ -381,8 +397,8 @@ class PvtSequence {
                 return requests.PvtGenerateVelocitiesAndTimesRequest.toBinary(this);
             },
         };
-        const response = await gateway.callAsync('device/pvt_generate_velocities_and_times', request, pvt_sequence_data_1.PvtSequenceData.fromBinary);
-        return response;
+        const response = await gateway.callAsync('device/pvt_generate_velocities_and_times', request, requests.PvtGenerateSequenceResponse.fromBinary);
+        return response.sequenceData;
     }
     /**
      * Waits until the live PVT sequence executes all queued actions.
@@ -622,9 +638,13 @@ class PvtSequence {
         return response.pvtMode;
     }
     /**
-     * Saves PvtSequenceData object as csv file.
+     * Saves PvtSequenceItem array as a csv file.
      * Save format is compatible with Zaber Launcher PVT Editor App.
      *
+     * Normally a sequence in memory should have relative time values on the points.
+     * If you want to store absolute times instead, you can use the
+     * ConvertTimeRelativeToAbsolute function to convert before saving.
+     *
      * Throws InvalidArgumentException if fields are undefined or inconsistent.
      * For example, position and velocity arrays must have the same dimensions.
      * Sequence lengths must be consistent for positions, velocities and times.
@@ -648,6 +668,10 @@ class PvtSequence {
     }
     /**
      * Load PVT Sequence data from CSV file.
+     * This function expects complete data in the CSV files (a time column and
+     * both position and velocity columns for each series).
+     * If your CSV file has partial data, use LoadPartialSequenceData instead.
+     *
      * The CSV data can include a header (recommended).
      * There are two possible header formats:
      *
@@ -666,6 +690,35 @@ class PvtSequence {
      * Time values default to milliseconds if no units are provided.
      * If no header is included, then column order is assumed to be "T,P1,V1,P2,V2,...".
      * In this case the number of columns must be odd.
+     *
+     * Users can add a column named "Relative" with true/false values to
+     * indicate whether each point's position is relative or absolute.
+     * If this column is not included, all points will be assumed to be absolute.
+     *
+     * If the first point has time = zero, it is considered the start position
+     * and treated specially. It must have an absolute position, and the device
+     * must already be idle at that position when the sequence is submitted.
+     * The velocity of the start position is ignored, and should normally be zero.
+     * Sequences with nonzero time for the first point do not have these constraints.
+     *
+     * Buffer calls and I/O actions can be added into the CSV file by
+     * adding a column titled "Actions", containing the ASCII protocol command(s)
+     * shortened by everything up to the PVT stream number, for example
+     * "call 2" or "io set do 1 1". If you want to insert multiple actions
+     * after a point, put them in the same cell separated by a semicolon.
+     * See the ASCII Protocol Manual
+     * [PVT command reference](https://www.zaber.com/protocol-manual?protocol=ASCII#topic_command_pvt)
+     * section for the list of available commands. Unit symbols are not supported;
+     * analog output voltages are always in volts and schedule delay times are
+     * always in milliseconds.
+     *
+     * Note that the Relative and Actions columns are not automatically
+     * detected, so if you include them you must include a header row.
+     *
+     * Time values should always be relative when sent to a device or to the
+     * various Generate... functions on this class. If you want to store
+     * absolute times in a CSV file, you can use the ConvertTimeRelativeToAbsolute
+     * function to convert after loading the file.
      * @param path The path to the csv file to load.
      * @returns The PVT csv data loaded from the file.
      */
@@ -681,7 +734,82 @@ class PvtSequence {
         return response;
     }
     /**
-     * Writes the contents of a PvtSequenceData object to the sequence.
+     * Load PVT Sequence data from CSV file, allowing for some combinations of incomplete data.
+     * Output from this function cannot be enqueued on a device until the missing data has
+     * been filled in using the GenerateVelocities, GeneratePositions or
+     * GenerateVelocitiesAndTimes functions.
+     *
+     * The CSV data can include a header (recommended).
+     * There are two possible header formats:
+     *
+     * 1. A time column with named position and velocity columns.
+     * For example, "Time (ms),X Position (cm),X Velocity (cm/s),...".
+     * In this case, position, velocity and time columns are all optional.
+     * Also, order does not matter, but position and velocity names must be consistent.
+     * This is our recommended CSV format.
+     *
+     * 2. A time column with alternating position and velocity columns.
+     * For example, "Time (ms),Position (cm),Velocity (cm/s),...".
+     * In this case, only the time column is optional and order does matter.
+     *
+     * Units must be wrapped in parens or square braces: ie. (µm/s), [µm/s].
+     * Additionally, native units are the default if no units are specified.
+     * Time values default to milliseconds if no units are provided.
+     * If no header is included, then column order is assumed to be "T,P1,V1,P2,V2,...".
+     * In this case the number of columns must be odd.
+     *
+     * Users can add a column named "Relative" with true/false values to
+     * indicate whether each point's position is relative or absolute.
+     * If this column is not included, all points will be assumed to be absolute.
+     *
+     * If the first point has time = zero, it is considered the start position
+     * and treated specially. It must have an absolute position, and the device
+     * must already be idle at that position when the sequence is submitted.
+     * The velocity of the start position is ignored, and should normally be zero.
+     * Sequences with nonzero time for the first point do not have these constraints.
+     *
+     * Buffer calls and I/O actions can be added into the CSV file by
+     * adding a column titled "Actions", containing the ASCII protocol command(s)
+     * shortened by everything up to the PVT stream number, for example
+     * "call 2" or "io set do 1 1". If you want to insert multiple actions
+     * after a point, put them in the same cell separated by a semicolon.
+     * See the ASCII Protocol Manual
+     * [PVT command reference](https://www.zaber.com/protocol-manual?protocol=ASCII#topic_command_pvt)
+     * section for the list of available commands. Unit symbols are not supported;
+     * analog output voltages are always in volts and schedule delay times are
+     * always in milliseconds.
+     *
+     * Note that the Relative and Actions columns are not automatically
+     * detected, so if you include them you must include a header row.
+     *
+     * Time values should always be relative when sent to a device or to the
+     * various Generate... functions on this class. If you want to store
+     * absolute times in a CSV file, you can use the ConvertTimeRelativeToAbsolute
+     * function to convert after loading the file.
+     * @param path The path to the csv file to load.
+     * @returns The PVT csv data loaded from the file.
+     */
+    static async loadPartialSequenceData(path) {
+        const request = {
+            ...requests.PvtLoadCsvRequest.DEFAULT,
+            path: path,
+            toBinary() {
+                return requests.PvtLoadCsvRequest.toBinary(this);
+            },
+        };
+        const response = await gateway.callAsync('device/stream_pvt_load_partial_csv', request, pvt_partial_csv_data_1.PvtPartialCsvData.fromBinary);
+        return response;
+    }
+    /**
+     * Writes the contents of a PvtSequenceItem array to the sequence.
+     * Each point must have its time value measured relative to the previous point
+     * or unexpected behavior will result. If your point times are absolute (measured
+     * from the start of the sequence), use the ConvertTimeAbsoluteToRelative
+     * function to convert them before submitting.
+     *
+     * If the first point in the sequence has a time value of zero, it is
+     * considered the starting position. It must have an absolute position,
+     * zero velocity, and the device must already be idle at the specified position.
      * @param sequenceData The PVT sequence data to submit.
      */
     async submitSequenceData(sequenceData) {
@@ -695,7 +823,81 @@ class PvtSequence {
                 return requests.PvtSubmitSequenceDataRequest.toBinary(this);
             },
         };
-        await gateway.callAsync('device/stream_pvt_submit_data', request);
+        await gateway.callAsync('device/stream_pvt_submit_sequence_data', request);
+    }
+    /**
+     * Converts the time values in a PvtSequenceItem array from absolute to relative.
+     * Points passed to the Generate functions or sent to devices must have relative time values.
+     * @param sequenceData The sequence data for which to convert times from absolute to relative.
+     * Point times must all be in the same units.
+     * @returns The sequence data with times converted from absolute to relative.
+     */
+    static async convertTimeAbsoluteToRelative(sequenceData) {
+        const request = {
+            ...requests.PvtConvertTimeRequest.DEFAULT,
+            fromAbsolute: true,
+            sequenceData: sequenceData,
+            toBinary() {
+                return requests.PvtConvertTimeRequest.toBinary(this);
+            },
+        };
+        const response = await gateway.callAsync('device/stream_pvt_convert_time', request, requests.PvtConvertTimeResponse.fromBinary);
+        return response.sequenceData;
+    }
+    /**
+     * Converts the time values in a PvtSequenceItem array from relative to absolute.
+     * @param sequenceData The sequence data for which to convert times from relative to absolute.
+     * Point times must all be in the same units.
+     * @returns The sequence data with times converted from relative to absolute.
+     */
+    static async convertTimeRelativeToAbsolute(sequenceData) {
+        const request = {
+            ...requests.PvtConvertTimeRequest.DEFAULT,
+            fromAbsolute: false,
+            sequenceData: sequenceData,
+            toBinary() {
+                return requests.PvtConvertTimeRequest.toBinary(this);
+            },
+        };
+        const response = await gateway.callAsync('device/stream_pvt_convert_time', request, requests.PvtConvertTimeResponse.fromBinary);
+        return response.sequenceData;
+    }
+    /**
+     * Converts the time values in a PvtPartialSequenceItem array from absolute to relative.
+     * Points passed to the Generate functions or sent to devices must have relative time values.
+     * @param sequenceData The sequence data for which to convert times from absolute to relative.
+     * Point times must all be in the same units.
+     * @returns The sequence data with times converted from absolute to relative.
+     */
+    static async convertTimeAbsoluteToRelativePartial(sequenceData) {
+        const request = {
+            ...requests.PvtPartialConvertTimeRequest.DEFAULT,
+            fromAbsolute: true,
+            sequenceData: sequenceData,
+            toBinary() {
+                return requests.PvtPartialConvertTimeRequest.toBinary(this);
+            },
+        };
+        const response = await gateway.callAsync('device/stream_pvt_convert_time_partial', request, requests.PvtPartialConvertTimeResponse.fromBinary);
+        return response.sequenceData;
+    }
+    /**
+     * Converts the time values in a PvtPartialSequenceItem array from relative to absolute.
+     * @param sequenceData The sequence data for which to convert times from relative to absolute.
+     * Point times must all be in the same units.
+     * @returns The sequence data with times converted from relative to absolute.
+     */
+    static async convertTimeRelativeToAbsolutePartial(sequenceData) {
+        const request = {
+            ...requests.PvtPartialConvertTimeRequest.DEFAULT,
+            fromAbsolute: false,
+            sequenceData: sequenceData,
+            toBinary() {
+                return requests.PvtPartialConvertTimeRequest.toBinary(this);
+            },
+        };
+        const response = await gateway.callAsync('device/stream_pvt_convert_time_partial', request, requests.PvtPartialConvertTimeResponse.fromBinary);
+        return response.sequenceData;
     }
 }
 exports.PvtSequence = PvtSequence;