# Location Functions

Location Functions simplify the process used to define point locations in relation to other locations, points, or a reference frame.

All of the functions return a vector of three values, which are x, y ,and z coordinates of the new location with respect to the Global Frame. When used to define points, the individual coordinates (x, y, or z) can be extracted by appending the corresponding vector index within square brackets [ ]

The following section provides a description for each of the functions along with their usage syntax and examples.

## loc_rel_to (coord_values, ref_marker)

Returns a set of three coordinate values in the Global Frame, to locate a given set of coordinate values, or a point or marker in a given reference frame.
Argument Data Type Description
coord_values An array of three values or a point or a marker variable name A set of coordinate values either as an array of three values or a variable name of an existing point or a marker.
ref_marker Marker variable name Variable name of the marker relative to which the point to be created.
Example:
 *SetPoint(p_new, loc_rel_to({10, 20, 30}, m_ref)[0], loc_rel_to({10, 20, 30}, m_ref)[1]), loc_rel_to({10, 20, 30}, m_ref)[2])) //Point created at x=10, y=20, z=30 with respect to marker m_ref *SetPoint(p_new, loc_rel_to(p_0, m_ref)[0], loc_rel_to(p_0, m_ref)[1], loc_rel_to(p_0, m_ref)[2]) // New point created by transforming point p_0 with respect to marker m_ref  *SetPoint(p_new, loc_rel_to(m_0, m_ref)[0], loc_rel_to(m_0, m_ref)[1], loc_rel_to(p_0, m_ref)[2]) // New point created by transforming point m_0 with respect to marker m_ref

## loc_cylindrical (coord_values, ref_marker)

Returns a set of three coordinate values in the Global Frame, to locate a given set of cylindrical coordinate values in a given reference frame.
Argument Data Type Description
coord_values An array of three values A set of three values in cylindrical coordinates.
ref_marker Marker variable name Variable name of the marker relative to which the point to be created.
Example:
 *SetPoint(p_new, loc_cylindrical({10, 0.5, 30}, m_ref)[0], loc_cylindrical({10, 0.5, 30}, m_ref)[1], loc_cylindrical({10, 0.5, 30}, m_ref)[2]) //Point created at a radius of 10, angle of 0.5 radians and at 30 units in z direction of marker m_ref. The point is created in XY plane of the marker at the specified z location. The angle is measured from the X axis of the marker, towards Y axis considered as positive *SetPoint(p_new, loc_cylindrical({10, 25d, 30}, m_ref)[0], loc_cylindrical({10, 25d, 30}, m_ref)[1], loc_cylindrical({10, 25d, 30}, m_ref)[2]) //Point created at a radius of 10, angle of 25 degrees and at 30 units in z direction of marker m_ref.

## loc_along_dir (origin, vector, distance)

Returns a set of three coordinate values in the Global Frame, to locate a point along a vector at a certain distance from an origin point.
Argument Data Type Description
origin An array of three values, or a point or marker variable name A set of coordinate values either as an array of three values or a variable name of point or a marker that represents the origin location from which the new location is to be determined.
vector Point or Vector variable name Variable name of the point or a vector entity that would define the direction from the point of origin along which the new location is to be determined.
distance Real Value representing the distance at which the new location is to be determined.
Example
 *SetPoint(p_new, loc_along_dir({10, 20, 30}, p_0, 25)[0], loc_along_dir({10, 20, 30}, p_0,25)[1], loc_along_dir({10, 0.5, 30}, p_0,25)[2]) //Point created at a distance of 25 units, from an origin at location x=10, y=20, z=30 along the direction of another existing point p_0.  *SetPoint(p_new, loc_along_dir(p_0, v_0, 25)[0], loc_along_dir(p_0, v_0,25)[1], loc_along_dir(p_0, v_0,25)[2]) //Point created at a distance of 25 units, from point p_0 along the direction of vector v_0

## loc_between (first_point, second_point, dist_ratio)

Returns a set of three coordinate values in the Global Frame, to locate a point between two points at a certain distance ratio.
Argument Data Type Description
first_point An array of three values or

a point or a marker variable name

A set of coordinate values either as an array of three values or a variable name of point or a marker that represents the first location.
second_point An array of three values or

a point or a marker variable name

A set of coordinate values either as an array of three values or a variable name of point or a marker that represents the second location.
dist_ratio Real Value between 0 and 1 representing the distance ratio at which the new location is to be determined. The distance ratio is the ratio of the distance between the new location from first location and distance between the first and second point.
Example
 *SetPoint(p_new, loc_between({10, 20, 30}, p_0, 0.5)[0], loc_between({10, 20, 30}, p_0, 0.5)[1], loc_between({10, 20, 30}, p_0, 0.5)[2]) //Point created at mid point of location (10, 20, 30) and point p_0  *SetPoint(p_new, loc_between(m_0, p_0, 0.3)[0], loc_between(m_0, p_0, 0.3)[1], loc_between(m_0, p_0, 0.3)[2]) //Point created between marker m_0 and point p_0 that is at a distance of 0.3 times the total distance between m_0 and p_0 from m_0

## loc_mirror (origin, ref_marker, "plane")

Returns a set of three coordinate values in the Global Frame, to locate a point symmetric with respect to a reference marker about its specified plane.
Argument Data Type Description
origin An array of three values or

a point or a marker variable name

A set of coordinate values either as an array of three values or a variable name of point or a marker that represents the first location.
ref_marker Marker variable name Variable name of the marker.
"plane" String Valid values are: XY, XZ, and YZ.
Example
 *SetPoint(p_new, loc_mirror({10, 20, 30}, m_ref, “XY”)[0], loc_mirror({10, 20, 30}, m_ref, “XY”)1]), loc_mirror({10, 20, 30}, m_ref, “XY”)[2])) //Point created by reflecting a location (at [10,20,30] w.r.t Global Frame) with respect to a marker m_ref about its XY plane *SetPoint(p_new, loc_mirror(p_0, m_ref, “YZ”)[0], loc_mirror(p_0, m_ref, “YZ”)1]), loc_mirror(p_0, m_ref, “YZ”)[2])) //Point created by reflecting a point p_0 about YZ plane of marker m_ref