Drake
 All Classes Files Functions Variables
CoordinateFrame Class Reference

Every input, state, and output in a DynamicalSystem has a coordinate frame attached to it. More...

Inheritance diagram for CoordinateFrame:
Collaboration diagram for CoordinateFrame:

Public Member Functions

function CoordinateFrame (name, dim, prefix, coordinates)
 Constructs a new coordinate frame. More...
 
function hasSamePrefix (frame1, frame2)
 useful for alarming on a possible prefix clash between two polys More...
 
function getPoly (obj)
 create the poly now if it hasn't been created yet More...
 
function disp (obj)
 
function isequal_modulo_transforms (a, b)
 returns true if the two coordinate frames are the same. More...
 
function getSym (obj)
 
function addTransform (obj, transform, bforce)
 Attaches a new coordinate transform from the current frame to a different frame. More...
 
function updateTransform (obj, newtransform)
 find a current transform with the same target frame and replace it with the new transform. More...
 
function addProjectionTransformByCoordinateNames (fr, fr2, fr2_defaultvals)
 adds a transform from fr to fr2 which copies over the dimensions with matching coordinate names, and sets the remaining elements of fr2 to their default values. More...
 
function drawFrameGraph (obj)
 Calls graphviz to visualize this frame plus all other frames that are reachable by some (potentially multi-hop) transform. More...
 
function findTransform (obj, target, options)
 Performs a simple breadth-first search of all available multi-hop transforms for a transformation from the current frame to the target frame. More...
 
function getCoordinateName (obj, i)
 
function findCoordinateIndex (obj, varname)
 
function getCoordinateNames (obj)
 getCoordinateNames encapsulates the lazy generation of the default coordinates. More...
 
function setCoordinateNames (obj, cnames)
 Updates the coordinate names. More...
 
function subFrame (obj, dims)
 Extracts a new frame with a subset of the original variables, so that fr.coordinates = obj.coordinates(dims) More...
 
function constructFrameWithAnglesWrapped (obj, angle_flag, q0)
 produces a copy of the current frame, but with a transform placed between them that wraps the angles around 2pi. More...
 
function scope (obj, t, val, options)
 publishes coordinate information to the lcm scope More...
 
function generateLCMType (obj, robot_name, signal_name)
 writes an lcm type specification to file from the coordinate frame description. More...
 
function getNumFrames (obj)
 
function getFrameByNum (obj, n)
 
function getFrameNum (obj, fr)
 
function setupMultiInput (obj, mdl, subsys)
 
function setupMultiOutput (obj, mdl, subsys)
 
function setupLCMInputs (obj, mdl, subsys, subsys_portnum, options)
 
function setupLCMOutputs (obj, mdl, subsys, subsys_portnum, options)
 
function autoConnect (fr1, fr2, connection)
 populates the connection structure as used in mimoCascade and mimoFeedback if connection is passed in, then it simply attempts to validate the connection. More...
 

Static Public Member Functions

static function stripSpecialChars (s)
 
static function generateDefaultCoordinates (prefix)
 generates the default coordinate labels for a coordinate Frame when no value is passed in, based on the prefixes provided. More...
 

Protected Member Functions

function ismember (obj, cell_of_frames)
 helper method for searching transforms More...
 
function extractFrameGraph (obj)
 

Detailed Description

Every input, state, and output in a DynamicalSystem has a coordinate frame attached to it.

Many bugs can be avoided by forcing developers to be explicit about these coordinate systems when they make combinations of systems.

Constructor & Destructor Documentation

function CoordinateFrame ( name  ,
dim  ,
prefix  ,
coordinates   
)

Constructs a new coordinate frame.

Parameters
nameis a string name associated with this coordinate frame
dimis the scalar number of elements in this frame
prefixis a single character for a mss_poly variable associated with this frame. you may also specify a vector of size dim of characters specifying the prefix for each variable.
Default: first character of name
coordinatesis a cell array (with dim elements) of strings of giving the names of the coordinates.
Default: x1,x2,x3 etc, where x is the prefix
Return values
objthe newly constructed CoordinateFrame

Member Function Documentation

function addProjectionTransformByCoordinateNames ( fr  ,
fr2  ,
fr2_defaultvals   
)

adds a transform from fr to fr2 which copies over the dimensions with matching coordinate names, and sets the remaining elements of fr2 to their default values.

Parameters
frthe coordinate frame which gets the new transform (from this frame)
fr2the coordinate frame that the transform maps to.
fr2_defaultvalsa double vector or Point which specifies the constant values of the elements in fr2 which do not get mapped from fr
function addTransform ( obj  ,
transform  ,
bforce   
)

Attaches a new coordinate transform from the current frame to a different frame.

An error is throw if there already exists any transform (or combination of transforms) that can already transform the current frame to the output frame.

Parameters
transforma CoordinateTransform object with the input frame matching this current frame.
bforceif true, then it forces the addition (overriding the search for existing transforms). This was added to optimize transform addition for the case when we are sure that no transform already exists. Use with caution.
function autoConnect ( fr1  ,
fr2  ,
connection   
)

populates the connection structure as used in mimoCascade and mimoFeedback if connection is passed in, then it simply attempts to validate the connection.

Return values
connection
function constructFrameWithAnglesWrapped ( obj  ,
angle_flag  ,
q0   
)

produces a copy of the current frame, but with a transform placed between them that wraps the angles around 2pi.

The transform wraps all coordinates with angle_flag = true to be inside [-pi+q0,pi+q0]

Parameters
angle_flagsboolean vector of length obj.dim which is true for each coordinate that will be wrapped around 2*pi.
q0double vector of with the default angle around which to perform the wrapping. it should be the length of the number of wrapped angles (e.g., so that x(angle_flags) = q0).
Return values
fr
function disp ( obj  )
function drawFrameGraph ( obj  )

Calls graphviz to visualize this frame plus all other frames that are reachable by some (potentially multi-hop) transform.

Note: requires that graphviz dot is installed on the system

function extractFrameGraph ( obj  )
protected
Return values
A
fr
function findCoordinateIndex ( obj  ,
varname   
)
Return values
ind
function findTransform ( obj  ,
target  ,
options   
)

Performs a simple breadth-first search of all available multi-hop transforms for a transformation from the current frame to the target frame.

Parameters
targeta CoordinateFrame that will be the output of the (possibly compound) CoordinateTransform
Options:
throw_error_if_fail 
Default: false
depth  positive scalar search depth.
Default: inf
Return values
tfthe resulting (possibly compound) transform, or the empty matrix if no transform was found.
theoptions structure sprinkled with extra information. this output enables recursive calls to the function, and is intended only for internal use.
static function generateDefaultCoordinates ( prefix  )
static

generates the default coordinate labels for a coordinate Frame when no value is passed in, based on the prefixes provided.

Return values
coordinates
function generateLCMType ( obj  ,
robot_name  ,
signal_name   
)

writes an lcm type specification to file from the coordinate frame description.

not to be used frequently.

function getCoordinateName ( obj  ,
 
)
Return values
str
function getCoordinateNames ( obj  )

getCoordinateNames encapsulates the lazy generation of the default coordinates.

It may be worth considering making lazy values a separate class; this would be advantageous in terms of making access to obj.coordinates even safer, rather than relying on future programmers to be careful enough to get the value of obj.coordinates only via getCoordinateNames. I'm not doing this in this instance since it's unclear how useful lazy values would be.

Return values
strs
function getFrameByNum ( obj  ,
 
)
Return values
fr
function getFrameNum ( obj  ,
fr   
)
Return values
id
function getNumFrames ( obj  )
Return values
n
function getPoly ( obj  )

create the poly now if it hasn't been created yet

Return values
p
function getSym ( obj  )
Return values
s
function hasSamePrefix ( frame1  ,
frame2   
)

useful for alarming on a possible prefix clash between two polys

Return values
tf
function isequal_modulo_transforms ( ,
 
)

returns true if the two coordinate frames are the same.

the "modulo transforms" refers to the fact that two identical frames, A and B, could be different if B knows how to transform to C, but A does not.

Return values
tf
function ismember ( obj  ,
cell_of_frames   
)
protected

helper method for searching transforms

Return values
tf
loc
function scope ( obj  ,
,
val  ,
options   
)

publishes coordinate information to the lcm scope

function setCoordinateNames ( obj  ,
cnames   
)

Updates the coordinate names.

Parameters
cnamesmust be a cell array vector of length dim populated with strings
function setupLCMInputs ( obj  ,
mdl  ,
subsys  ,
subsys_portnum  ,
options   
)
function setupLCMOutputs ( obj  ,
mdl  ,
subsys  ,
subsys_portnum  ,
options   
)
function setupMultiInput ( obj  ,
mdl  ,
subsys   
)
Return values
insys
function setupMultiOutput ( obj  ,
mdl  ,
subsys   
)
Return values
outsys
static function stripSpecialChars ( )
static
Return values
s
function subFrame ( obj  ,
dims   
)

Extracts a new frame with a subset of the original variables, so that fr.coordinates = obj.coordinates(dims)

Parameters
dimsa numeric vector of index values such that fr.coordinates = obj.coordinates(dims)
Return values
thenewly constructed frame
function updateTransform ( obj  ,
newtransform   
)

find a current transform with the same target frame and replace it with the new transform.

this only searches simple transforms (from the current frame to the output frame), not multi-hop transforms through multiple frames.


The documentation for this class was generated from the following file: