Class AdvMotion

Defined in File AdvancedMotionApi.h

Nested Relationships

Nested Types

Class Documentation

class AdvMotion

This class contains advanced position command functions.

Public Functions

inline AdvMotion(AdvancedMotion *f)

bool IsDeviceValid()

WMX3APIFUNC CreateSplineBuffer(int channel, unsigned int points)

Allocate buffer memory for a spline execution channel.

When the WMX3 engine is started, no memory is allocated for execution of spline motion commands. This function must be called before a spline motion command can be executed.

Remark

Each channel has a separate buffer memory space. This function must be called for each channel before that channel can execute spline motion commands. Each channel can execute one spline motion command at one time. To execute two spline motion commands at the same time, buffer memory space must be allocated for two channels. However, if two spline motion commands are executed sequentially with no overlap, only one channel is required, even if the spline motion commands control different axes.

Allocating buffer memory space is an operation that can fail due to lack of memory space or fragmentation of memory. For deterministic operation, this function should be called during initialization to allocate memory for all spline execution channels that will potentially be used by the program.

The maximum size of the buffer memory space of a spline execution channel is 2GB-1Byte (2147483647 bytes). Specifying a larger size will cause this function to return the RequestedBufferTooLarge error.

It is not necessary to call this function again after buffer memory has been allocated once. (When the WMX3 engine is restarted, this function must be called again to allocate buffer memory.)

Buffer memory that has been allocated can be freed using the FreeSplineBuffer function. After freeing the buffer memory of a spline execution channel, this function can be called again to reallocate a different amount of buffer memory.

It is not necessary to free allocated memory using FreeSplineBuffer before exiting the program. Any allocated memory is automatically freed when the WMX3 engine is closed.

The GetSplineBufferPoints function can be used to find the amount of buffer memory currently allocated to a spline execution channel.

The GetSplineBytesPerPoint function can be used to convert the buffer memory size from points to bytes.

See also

Spline

Parameters:

channel – [in] The spline execution channel. The maximum number of available channels is maxSplineChannel.
points – [in] The number of points to allocate memory for. Each spline point occupies one point in the memory. Setting the sampleMultiplier parameter of a VelAccLimitedSplineCommand to a value greater than 1 will multiply the number of points occupied by one spline point. For example, if sampleMultiplier is set to 10, each point in the spline will require 10 points worth of buffer memory to store.

WMX3APIFUNC FreeSplineBuffer(int channel)

Free buffer memory for a spline execution channel.

This function frees the buffer memory that has been allocated with the CreateSplineBuffer function. This allows CreateSplineBuffer to be called again to allocate a different amount of memory.

Remark

It is not necessary to call this function before exiting the program, as any allocated memory is automatically freed when the WMX3 engine closes.

The freed memory, after a brief delay, will become available for the system to use for another purpose.

Parameters:: channel – [in] The spline execution channel. The maximum number of available channels is maxSplineChannel.

WMX3APIFUNC GetSplineBufferPoints(int channel, unsigned int *pPoints)

Get the amount of buffer memory currently allocated to a spline execution channel.

This function obtains the amount of buffer memory currently allocated to a spline execution channel, in units of points.

Remark

To convert the buffer memory size from the number of points to bytes, use the GetSplineBytesPerPoint function.

If no buffer memory has been allocated to the specified channel yet, this function will return 0 in the pPoints parameter.

Parameters:

channel – [in] The spline execution channel. The maximum number of available channels is maxSplineChannel.
pPoints – [out] A pointer to an unsigned int that will contain the number of points that can be stored in the buffer memory.

WMX3APIFUNC GetSplineBytesPerPoint(unsigned int *pBytes)

Get the number of bytes required per point data in the spline execution buffer memory.

This function obtains the number of bytes of memory required to store one point data in the spline execution buffer memory. This can be used to calculate the number of bytes of buffer memory required to store a particular number of points. For example, if this function returns 192, the number of bytes required to store 100000 points is 192*100000 = 19200000, or approximately 18.3MB.

Remark

Parameters:: pBytes – [out] A pointer to an unsigned int that will contain the number of bytes of memory required per point data.

WMX3APIFUNC StartCSplinePos(int channel, PointTimeSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint, double *pPointTimeMilliseconds)

Start a cubic spline motion command in which the time at each point is specified. The point positions are specified as absolute positions.

During a cubic spline motion, the commanded axes will traverse each point in order at the specified times. The velocities and accelerations of the commanded axes will be continuous throughout the entire motion, so the resulting path will be smooth. However, if the points and times are not specified carefully, the commanded axes may reach a very high velocity or acceleration during the motion (although the velocity and acceleration will still be continuous).

Remark

This type of spline is suitable if the time at which each point is traversed must be specified.

The first point will automatically be set to the current position of the commanded axes, and does not need to be passed to this function. If the first point passed to this function is equal to the current position of the commanded axes, that point will be ignored.

The time at each point must be specified in ascending order, or else an error will be returned. The first time will automatically be set to 0, and does not need to be passed to this function. If the first time passed to this function is equal to 0, that time will be ignored.

When stopping the spline motion using the Stop function, the interpolating axes will decelerate to a stop along the spline path using the approximate maximum composite acceleration that would be applied to the axes when executing the spline command.

The minimum time between points is 1 microsecond (1e-3 milliseconds). Exceeding this limit will cause the TimeBetweenPointsTooClose error to be returned.

The minimum distance between points is 1e-6 user units. If there are consecutive points with less than this distance, the latter point will be ignored. If this causes the number of points to be less than 2 (excluding the first point), the PointCountBelowMinimum error will be returned.

See also

Spline

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a PointTimeSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.
pPointTimeMilliseconds – [in] An array of doubles that contain the spline time data. The N-th index of the array specifies the time data of the N-th index of the pPoint array. The length of the array must be equal to numPoints. The times are specified in units of milliseconds.

WMX3APIFUNC StartCSplinePos(int channel, TotalTimeSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint)

Start a cubic spline motion command in which the total time to complete the spline is specified. The point positions are specified as absolute positions.

During a cubic spline motion, the commanded axes will traverse each point, completing the spline using the specified total time. The velocities and accelerations of the commanded axes will be continuous throughout the entire motion, so the resulting path will be smooth. The velocity along the spline will be relatively constant, so one or more commanded axes may undergo high acceleration if there is a sharp corner in the given point data.

Remark

The time at which each point is traversed is calculated taking into account the distance between the points, the acceleration at the beginning, and the deceleration at the end.

This type of spline is suitable for motion where the total time to complete the spline is important, and there is no sharp corner in the given point data. If there is a sharp corner in the point data, one or more commanded axes may undergo high acceleration, even if the velocity along the spline is relatively constant. At these sharp corners, the velocity may also suddenly and momentarily increase or decrease.

The first point will automatically be set to the current position of the commanded axes, and does not need to be passed to this function. If the first point passed to this function is equal to the current position of the commanded axes, that point will be ignored.

When stopping the spline motion using the Stop function, the interpolating axes will decelerate to a stop along the spline path using the approximate maximum composite acceleration that would be applied to the axes when executing the spline command.

The minimum time between points is 1 microsecond (1e-3 milliseconds). Exceeding this limit will cause the TimeBetweenPointsTooClose error to be returned.

The minimum distance between points is 1e-6 user units. If there are consecutive points with less than this distance, the latter point will be ignored. If this causes the number of points to be less than 2 (excluding the first point), the PointCountBelowMinimum error will be returned.

See also

Spline

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a TotalTimeSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.

WMX3APIFUNC StartCSplinePos(int channel, ProfileSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint)

Start a cubic spline motion command in which the spline is traversed using a motion profile. The point positions are specified as absolute positions.

During a cubic spline motion, the commanded axes will traverse each point, traveling along the spline using the specified motion profile. The velocities and accelerations of the commanded axes will be continuous throughout the entire motion, so the resulting path will be smooth. The velocity along the spline will be relatively constant, so one or more commanded axes may have high acceleration if there is a sharp corner in the given point data.

Remark

Compared to StartCSplinePos, this function has the following differences:

The velocity, acceleration, jerk, etc. that is used is directly specified instead of being calculated from the specified time.

All available profile shapes in ProfileType can be used.

Acceleration and deceleration along the spline path can stretch over several points or a fraction of a point. With StartCSplinePos, acceleration along the spline path occurs only between the first point and second point, and deceleration along the spline path occurs only between the last point and second to last point.

This type of spline is suitable for motion where the velocity, acceleration, and profile shape along the spline path needs to be specified, and there is no sharp corner in the given point data. If there is a sharp corner in the point data, one or more commanded axes may undergo high acceleration, even if the velocity along the spline is relatively constant. At these sharp corners, the velocity may also suddenly and momentarily increase or decrease.

The first point will automatically be set to the current position of the commanded axes, and does not need to be passed to this function. If the first point passed to this function is equal to the current position of the commanded axes, that point will be ignored.

When stopping the spline motion using the Stop function, the interpolating axes will gradually stop along the spline path using the deceleration parameters specified in the profile argument.

The minimum time between points is 1 microsecond (1e-3 milliseconds). Exceeding this limit will cause the TimeBetweenPointsTooClose error to be returned.

The minimum distance between points is 1e-6 user units. If there are consecutive points with less than this distance, the latter point will be ignored. If this causes the number of points to be less than 2 (excluding the first point), the PointCountBelowMinimum error will be returned.

If a large value is specified for the sampleMultiplier parameter, the time and distance between points will become smaller from the added sample points, and may cause the TimeBetweenPointsTooClose or DistanceBetweenPointsTooClose errors to be returned. If this occurs, reduce the sampleMultiplier.

See also

Spline

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a ProfileSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.

WMX3APIFUNC StartCSplinePos(int channel, VelAccLimitedSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint)

Start a cubic spline motion command in which the spline is traversed while staying within the specified velocity and acceleration limits for each axis. The point positions are specified as absolute positions.

During a cubic spline motion, the commanded axes will traverse each point, traveling along the spline at the specified velocity and acceleration, while staying within the velocity and acceleration limits of each individual axis.

Remark

This type of spline is suitable for point data containing sharp corners. Each axis will decelerate at corners to stay within the velocity and acceleration limits of that axis. The entire spline is considered when calculating the deceleration, so the axes may start to decelerate from several points before the sharp corner. The deceleration is optimized so that the spline will be traversed in approximately the shortest amount of time possible with the given velocity and acceleration constraints.

Because the velocities and accelerations along the spline are sampled at certain non-constant intervals (that are typically greater than one cycle), there will be some approximation and the velocities and accelerations during some cycles may exceed the specified composite values or the limits by a small percentage. Increasing the sample count can improve the accuracy of the velocity and acceleration limits.

The first point will automatically be set to the current position of the commanded axes, and does not need to be passed to this function. If the first point passed to this function is equal to the current position of the commanded axes, that point will be ignored.

When stopping the spline motion using the Stop function, the interpolating axes will decelerate to a stop along the spline path using the approximate maximum composite acceleration that would be applied to the axes when executing the spline command.

The minimum time between points is 1 microsecond (1e-3 milliseconds). Exceeding this limit will cause the TimeBetweenPointsTooClose error to be returned.

The minimum distance between points is 1e-6 user units. If there are consecutive points with less than this distance, the latter point will be ignored. If this causes the number of points to be less than 2 (excluding the first point), the PointCountBelowMinimum error will be returned.

If a large value is specified for the sampleMultiplier parameter, the time and distance between points will become smaller from the added sample points, and may cause the TimeBetweenPointsTooClose or DistanceBetweenPointsTooClose errors to be returned. If this occurs, reduce the sampleMultiplier.

See also

Spline

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a VelAccLimitedSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.

WMX3APIFUNC StartCSplineMov(int channel, PointTimeSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint, double *pPointTimeMilliseconds)

Start a cubic spline motion command in which the time at each point is specified. The point positions are specified as relative positions.

This is a relative position version of the StartCSplinePos function, where all point positions are specified relative to the command positions of the commanded axes at the time that this function is executed.

Remark

See also

Spline

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a PointTimeSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.
pPointTimeMilliseconds – [in] An array of doubles that contain the spline time data. The N-th index of the array specifies the time data of the N-th index of the pPoint array. The length of the array must be equal to numPoints. The times are specified in units of milliseconds.

WMX3APIFUNC StartCSplineMov(int channel, TotalTimeSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint)

Start a cubic spline motion command in which the total time to complete the spline is specified. The point positions are specified as relative positions.

This is a relative position version of the StartCSplinePos function, where all point positions are specified relative to the command positions of the commanded axes at the time that this function is executed.

Remark

See also

Spline

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a TotalTimeSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.

WMX3APIFUNC StartCSplineMov(int channel, ProfileSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint)

Start a cubic spline motion command in which the spline is traversed using a motion profile. The point positions are specified as relative positions.

This is a relative position version of the StartCSplinePos function, where all point positions are specified relative to the command positions of the commanded axes at the time that this function is executed.

Remark

See also

Spline

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a ProfileSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.

WMX3APIFUNC StartCSplineMov(int channel, VelAccLimitedSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint)

Start a cubic spline motion command in which the spline is traversed while staying within the specified velocity and acceleration limits for each axis. The point positions are specified as relative positions.

This is a relative position version of the StartCSplinePos function, where all point positions are specified relative to the command positions of the commanded axes at the time that this function is executed.

Remark

See also

Spline

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a VelAccLimitedSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.

WMX3APIFUNC StartCSplinePos(int channel, PointTimeSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint, double *pPointTimeMilliseconds, Trigger *pTrigger)

Start a triggered cubic spline motion command in which the time at each point is specified. The point positions are specified as absolute positions.

During a cubic spline motion, the commanded axes will traverse each point in order at the specified times. The velocities and accelerations of the commanded axes will be continuous throughout the entire motion, so the resulting path will be smooth. However, if the points and times are not specified carefully, the commanded axes may reach a very high velocity or acceleration during the motion (although the velocity and acceleration will still be continuous).

Remark

This type of spline is suitable if the time at which each point is traversed must be specified.

The first point will automatically be set to the current position of the commanded axes, and does not need to be passed to this function. If the first point passed to this function is equal to the current position of the commanded axes, that point will be ignored.

The time at each point must be specified in ascending order, or else an error will be returned. The first time will automatically be set to 0, and does not need to be passed to this function. If the first time passed to this function is equal to 0, that time will be ignored.

When stopping the spline motion using the Stop function, the interpolating axes will decelerate to a stop along the spline path using the approximate maximum composite acceleration that would be applied to the axes when executing the spline command.

The minimum time between points is 1 microsecond (1e-3 milliseconds). Exceeding this limit will cause the TimeBetweenPointsTooClose error to be returned.

The minimum distance between points is 1e-6 user units. If there are consecutive points with less than this distance, the latter point will be ignored. If this causes the number of points to be less than 2 (excluding the first point), the PointCountBelowMinimum error will be returned.

The motion will begin when the specified trigger condition is satisfied.

See also

Spline, Trigger Motion

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a PointTimeSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.
pPointTimeMilliseconds – [in] An array of doubles that contain the spline time data. The N-th index of the array specifies the time data of the N-th index of the pPoint array. The length of the array must be equal to numPoints. The times are specified in units of milliseconds.
pTrigger – [in] A pointer to an object of the Trigger class that specifies the trigger condition.

WMX3APIFUNC StartCSplinePos(int channel, TotalTimeSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint, Trigger *pTrigger)

Start a triggered cubic spline motion command in which the total time to complete the spline is specified. The point positions are specified as absolute positions.

During a cubic spline motion, the commanded axes will traverse each point, completing the spline using the specified total time. The velocities and accelerations of the commanded axes will be continuous throughout the entire motion, so the resulting path will be smooth. The velocity along the spline will be relatively constant, so one or more commanded axes may undergo high acceleration if there is a sharp corner in the given point data.

Remark

The time at which each point is traversed is calculated taking into account the distance between the points, the acceleration at the beginning, and the deceleration at the end.

This type of spline is suitable for motion where the total time to complete the spline is important, and there is no sharp corner in the given point data. If there is a sharp corner in the point data, one or more commanded axes may undergo high acceleration, even if the velocity along the spline is relatively constant. At these sharp corners, the velocity may also suddenly and momentarily increase or decrease.

The first point will automatically be set to the current position of the commanded axes, and does not need to be passed to this function. If the first point passed to this function is equal to the current position of the commanded axes, that point will be ignored.

When stopping the spline motion using the Stop function, the interpolating axes will decelerate to a stop along the spline path using the approximate maximum composite acceleration that would be applied to the axes when executing the spline command.

The minimum time between points is 1 microsecond (1e-3 milliseconds). Exceeding this limit will cause the TimeBetweenPointsTooClose error to be returned.

The minimum distance between points is 1e-6 user units. If there are consecutive points with less than this distance, the latter point will be ignored. If this causes the number of points to be less than 2 (excluding the first point), the PointCountBelowMinimum error will be returned.

The motion will begin when the specified trigger condition is satisfied.

See also

Spline, Trigger Motion

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a TotalTimeSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.
pTrigger – [in] A pointer to an object of the Trigger class that specifies the trigger condition.

WMX3APIFUNC StartCSplinePos(int channel, ProfileSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint, Trigger *pTrigger)

Start a triggered cubic spline motion command in which the spline is traversed using a motion profile. The point positions are specified as absolute positions.

During a cubic spline motion, the commanded axes will traverse each point, traveling along the spline using the specified motion profile. The velocities and accelerations of the commanded axes will be continuous throughout the entire motion, so the resulting path will be smooth. The velocity along the spline will be relatively constant, so one or more commanded axes may have high acceleration if there is a sharp corner in the given point data.

Remark

Compared to StartCSplinePos, this function has the following differences:

The velocity, acceleration, jerk, etc. that is used is directly specified instead of being calculated from the specified time.

All available profile shapes in ProfileType can be used.

Acceleration and deceleration along the spline path can stretch over several points or a fraction of a point. With StartCSplinePos, acceleration along the spline path occurs only between the first point and second point, and deceleration along the spline path occurs only between the last point and second to last point.

This type of spline is suitable for motion where the velocity, acceleration, and profile shape along the spline path needs to be specified, and there is no sharp corner in the given point data. If there is a sharp corner in the point data, one or more commanded axes may undergo high acceleration, even if the velocity along the spline is relatively constant. At these sharp corners, the velocity may also suddenly and momentarily increase or decrease.

The first point will automatically be set to the current position of the commanded axes, and does not need to be passed to this function. If the first point passed to this function is equal to the current position of the commanded axes, that point will be ignored.

When stopping the spline motion using the Stop function, the interpolating axes will gradually stop along the spline path using the deceleration parameters specified in the profile argument.

The minimum time between points is 1 microsecond (1e-3 milliseconds). Exceeding this limit will cause the TimeBetweenPointsTooClose error to be returned.

The minimum distance between points is 1e-6 user units. If there are consecutive points with less than this distance, the latter point will be ignored. If this causes the number of points to be less than 2 (excluding the first point), the PointCountBelowMinimum error will be returned.

If a large value is specified for the sampleMultiplier parameter, the time and distance between points will become smaller from the added sample points, and may cause the TimeBetweenPointsTooClose or DistanceBetweenPointsTooClose errors to be returned. If this occurs, reduce the sampleMultiplier.

The motion will begin when the specified trigger condition is satisfied.

See also

Spline, Trigger Motion

Parameters:

channel – [in] The spline channel to execute the spline motion command.
pSplineCommand – [in] A pointer to a ProfileSplineCommand that contains the spline parameters.
numPoints – [in] The number of points in the pPoint array that is passed to this function. This value must be at least 2.
pPoint – [in] An array of SplinePoint objects that contain the spline point data. The length of the array must be equal to numPoints.
pTrigger – [in] A pointer to an object of the Trigger class that specifies the trigger condition.

WMX3APIFUNC StartCSplinePos(int channel, VelAccLimitedSplineCommand *pSplineCommand, unsigned int numPoints, SplinePoint *pPoint, Trigger *pTrigger)

Start a triggered cubic spline motion command in which the spline is traversed while staying within the specified velocity and acceleration limits for each axis. The point positions are specified as absolute positions.