msim.serialization

Class DAELoader

java.lang.Object

msim.serialization.DAELoader

@ThreadSafe
public class DAELoader
extends java.lang.Object

Facility to construct a Linkage sub-tree from a COLLADA scenegraph.

See also DAEExporter.

MSim reads and writes only the (valid) COLLADA 1.5.0 subset enumerated below. Other elements and attributes are ignored, and are not guaranteed to be preserved across a DAELoad/DAEExport.

There are multiple possibilities for associating an MSim linkage with different types of COLLADA structures, including:

• a COLLADA visual scene graph
• a COLLADA physics model
• a COLLADA kinematics model

Currently only the first (visual scene graph) is supported. None of the possible COLLADA structures natively offers sufficient representation for all MSim state, and hence any choice will require some use of COLLADA "extra" elements. COLLADA kinematics seems to come the closest, however,

• the COLLADA joint mobility model differs significantly from MSim
• COLLADA kinematics does not include any structure corresponding to MSim sublinkages
• COLLADA kinematics "attachment_*" does not support representing all aspects of MSim user link subframes
• the "bind_kinematics_model" and "bind_joint_axis" elements that COLLADA uses to link a kinematics model to a visual scene appear to be insufficient to handle fully general kinematic graph topologies (see COLLADA spec bug 218)
• very few examples of COLLADA kinematics are currently available, and very few other software systems currently read or write COLLADA kinematics.

MSim and COLLADA Model Correspondence

The MSim linkage model corresponds to (a sub-tree of) a COLLADA visual scene graph. The COLLADA root element for the correspondence is either a "node" or a "visual_scene", either in a library or instanced. Instances are automatically dereferenced; "visual_scene" is treated as a "node" with no user widgets. The correspondence parrallels that implemented in J3DLoader: the MSim linkage spanning tree has the same topology as the COLLADA subtree.

Each "instance_geometry" of a COLLADA node induces a user widget on the corresponding MSim Link (see vona.dae.DAEUtils.daeGeometryInstanceToWidget()).

Unless COLLADA "extra" elements are present containing "profile=MSim" "technique", as described in detail below, all joints are initially inferred as Joint.Type.GENERAL with identity child-to-mobility and mobility transforms, and mobility-to-parent transform set to the corresponding COLLADA "node" child-to-parent transform.

Behavior is undefined if the COLLADA visual scene graph contains a self-referential "instance_node". Any encountered non-rigid COLLADA transforms are treated as identity.

COLLADA "extra" elements for MSim

Upon loading a COLLADA model, this loader will look for COLLADA "extra" elements that are children of COLLADA "node"s. If such an element is present and has a "technique" child with "profile" attribute equal to "MSim", then the XML contents of the technique are used to

• set whether the containing COLLADA node should correspond to an MSim link (and its parent joint), an MSim closure joint, or an MSim link user subframe
• specify all state of the corresponding MSim entities, including joint type, closure joint child, joint mobility positioning transforms, etc.

Full details are given below.

DAEExporter writes these "extra" elements.

Name and Cross-Reference Handling

This loader expects all URI in the COLLADA document to be URL fragments of the form "#IDREF". This includes

• all "url" attributes of "instance_FOO" elements
• the "target" attribute of "instance_material"
• the "source" attributes of "accessor" and "input".

In all but the last two cases the IDREF must resolve to an element in the corresponding library.

The "source" attribute of an accessor element must resolve to an array within a(ny) "source" element (yes, there are both "source" attributes and elements).

The "source" of a "vertices/input" element must resolve to a(ny) "source" element. Outside of a "vertices" element, the "source" of an "input" element with "semantic=VERTEX" must resolve to a(ny) "vertices" element, and the "source" of an "input" element with "semantic!=VERTEX" must resolve to a(ny) "source" element.

Other than URI, there is one additional type of cross reference in the COLLADA subset handled by MSim: The "material" attributes within descendants of the "geometry" referenced by an "instance_geometry" must resolve to corresponding "symbol" attributes of "instance_material" within that same "instance_geometry".

This loader must associate names to many of the MSim entities that are induced by corresponding COLLADA elements. If the COLLADA element has an "extra" child with a profile=MSim "technique" then the name is taken from the name attribute, if any, of the "msim_link", "msim_closure", or "msim_user_subframe" COLLADA element.

In the absence of a COLLADA extra element with a profile=MSim technique, or if there was no name attribute on the appropriate descendant thereof, the name is based on the content of the following COLLADA attributes, if present, in priority order: "name", "id", "sid".

If none of the above are present, a unique name is automatically generated. Otherwise, the name is sanitized by converting any characters not allowed in an MSim name to underscores, and the name is made unique within any necessary context (by appending a deterministically generated suffix). Once an MSim name has been associated to a COLLADA element, that name will be used consistently.

COLLADA Subset

Following is a summary of the subset of COLLADA 1.5.0 supported in MSim. This is a valid subset in the sense that instance documents consisting only of elements and attributes in this subset validate against the official schema.

Unsupported features include:

• external references
• lookat and any transforms with skew or non-uniform scale
• COLLADA kinematics (see above)
• animation
• skin and bones
• cameras and lighting
• splines, polygons, and polylists
• forumulas and params (except in accessor)
• LoD, layers, and passes
• effects other than profile_COMMON
• texturing
• physics and b-rep.

   COLLADA: xmlns=http://www.collada.org/2008/03/COLLADASchema
            version=1.5.0 
     asset
     {library_geometries|library_nodes|library_visual_scenes
     |library_materials|library_effects}*
     scene
       [instance_visual_scene]: [sid] url-to-visual-scene

   library_FOOs: [id]
     FOO+

   asset
     created
       xs:dateTime
     modified
       xs:dateTime

   extra: [id] [type]
     technique+

   technique: profile [xmlns]
     any well formed XML

   visual_scene: [id]
     node+
     extra*
       technique: profile="MSim"
         msim_link|msim_closure|msim_user_subframe|msim_skip

   node: [id] [sid]
     {matrix //MSim ignores matrices with skew or non-uniform scale
       float4x4
     |scale //msim ignores non-uniform scale
       float3
     |rotate
       float4
     |translate}*
       float3
     instance_geometry*: url-to-geometry [sid] [name]
       [bind_material]
         technique_common
           instance_material+: url-to-target-material symbol
     instance_node*: [sid] url-to-node
     node*
     extra*
       technique: profile="MSim"
         msim_link|msim_closure|msim_user_subframe|msim_skip

   geometry: [id]
     mesh
       source+: id
         float_array: [id] count [digits (def 6)] [magnitude (def 38)]
           list of float
         [technique_common]
           accessor: count [offset] url-to-source [stride]
             param*: name type=float
       vertices: id
         input+: semantic url-to-source
           //one input must have semantic=POSITION
       {lines|linestrips|triangles|trifans|tristrips}*: count [material-sym]
         input*: offset semantic=VERTEX|POSITION|NORMAL|COLOR source
           //if any input then one must have semantic=VERTEX
         p* //at most one for lines and triangles
           list of uint

   material: [id]
     instance_effect: url-to-effect

   effect: id
     profile_COMMON+:
       technique: sid=COMMON
         constant|lambert|phong|blinn
           [emission]
           [ambient] [diffuse] //only in lambert, phong, and blinn
           [specular] [shininess] //only in phong and blinn
           [transparency]

   emission, ambient, diffuse, specular
     color
       float4

   shininess, transparency
     float

   msim_link: [name] explicit_flags
     [mass_props]: [mass] [com_widget_scale]
                   [com_widget_enabled] [subtree_com_widget_enabled]
       link_com
         x y z
     [ground_link]: [sublinkage_name] [sublinkage_disposition]
     [parent_joint]: [name] joint_type
                     [mobility_inverted] [positioning_transforms_locked]
                     [soft_goal_priority] [soft_goal_weight]
                     explicit_flags
       child_to_mobility, mobility_to_parent
         (tx ty tz ex ey ez)|subframe_name
       [dof_limits]
         ((lower upper)|(NaN NaN))*
       [dof_target], [dof_posture], [dof_lock]
         (double|NaN)* //corresponding to joint DoF
       [stiffness_props]: [stiffness] [stiffness_rest] [enabled]

   msim_closure: same attributes as parent_joint
     same child elements as parent_joint plus
     child_link
       absolute msim path to child link

   msim_user_subframe: name [subframe_type]
     [connectable_subframe_types]
       subframe_type*
     [connectable_joint_types]
       joint_type*

   msim_skip: to //sidref to replacement node

   explicit_flags = [explictly_visible] [explicitly_hidden]
                    [explicitly_highlighted] [explicitly_masked]

   joint_type = revolute|prismatic|cylindrical|spherical|planar|
                cartesian2|cartesian3|pin_slider|point_slider|point_plane|
                general

   sublinkage_disposition = driving|driven|simultaneous

 

TBD

• serialize propertyMaps on Linkage, LinkageNode, and Widget
• serialize MSim gravity settings
• possible extensions to COLLADA physics and/or kinematics
• also permit collada 1.4 as currently we may not really be using any 1.5 specific features anyway

Copyright (C) 2010 Marsette A. Vona, III

Author:

Marsette A. Vona, III

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	DAELoader.LatentClosure record containing all needed info to construct a closure joint

Field Summary

Fields

Modifier and Type	Field and Description
private static java.lang.String	cvsid
protected static vona.dae.util.DAEUtils	daeUtils for now use the singleton DAEUtils
static int	MAX_UNIQUE_NAME_TRIES maximum tries to make a unique name
static java.lang.String	MSIM_EXTRA_PROP DAEObject msim property key
static java.lang.String	MSIM_NAME_PROP DAEObject msim property key
static java.lang.String	MSIM_PARENT_JOINT_NAME_PROP DAEObject msim property key
static java.lang.String	MSIM_ROOT_PROP DAEObject msim property key
static java.lang.String	MSIM_RX_PROP DAEObject msim property key
protected static int	nextAnonymousNameIndex used to generate unique names for DAE elements
protected static int	nextUniqueJointNameIndex used to generate unique names for DAE elements
protected static int	nextUniqueLinkNameIndex used to generate unique names for DAE elements
protected static int	nextUniqueWidgetNameIndex used to generate unique names for DAE elements
protected static javax.xml.bind.Unmarshaller	unmarshaller unmarshaller for DAE MSim extras

Constructor Summary

Constructors

Constructor and Description
DAELoader()

Method Summary

Methods

Modifier and Type	Method and Description
static DAEMSimExtra	getExtra(vona.dae.util.DAEObject obj) Unmarshal the first DAEMSimExtra in an DAEMSimExtra.MSIM_PROFILE DAE "technique" child of an "extra" child of obj, if any.
static java.lang.String	getName(vona.dae.util.DAEObject obj) Resolve (or create) an MSim name for obj.
static vona.math.RX	getRX(vona.dae.util.DAEObject obj) Resolve (or create) an MSim RX for obj.
protected static void	loadChildFromDAE(vona.dae.jaxb.dae.NodeType source, Link parent, boolean loadGeoms, java.util.List<DAELoader.LatentClosure> latentClosures) Load a COLLADA "node" child.
static Link	loadFromDAE(vona.dae.jaxb.dae.COLLADA dae) loadFromDAE(Link, COLLADA, String, boolean), loading geometries, consing a new linkage root, and inferring the DAE root.
static Link	loadFromDAE(vona.dae.jaxb.dae.COLLADA dae, java.lang.String daeRoot) loadFromDAE(Link, COLLADA, String, boolean), loading geometries and consing a new linkage root.
static Link	loadFromDAE(Link linkageRoot, vona.dae.jaxb.dae.COLLADA dae, java.lang.String daeRoot) loadFromDAE(Link, COLLADA, String, boolean), loading geometries.
static Link	loadFromDAE(Link linkageRoot, vona.dae.jaxb.dae.COLLADA dae, java.lang.String daeRoot, boolean loadGeometries) Load a Linkage sub-tree from a COLLADA visual scene graph.
protected static Link	loadLinkFromDAE(Link link, vona.dae.util.DAEObject source, Link parentLink, boolean loadGeoms, java.util.List<DAELoader.LatentClosure> latentClosures) Load an MSim Link from a DAE element.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

cvsid

private static final java.lang.String cvsid

See Also:

Constant Field Values

MSIM_EXTRA_PROP

public static final java.lang.String MSIM_EXTRA_PROP

DAEObject msim property key

See Also:

Constant Field Values

MSIM_NAME_PROP

public static final java.lang.String MSIM_NAME_PROP

DAEObject msim property key

See Also:

Constant Field Values

MSIM_PARENT_JOINT_NAME_PROP

public static final java.lang.String MSIM_PARENT_JOINT_NAME_PROP

DAEObject msim property key

See Also:

Constant Field Values

MSIM_RX_PROP

public static final java.lang.String MSIM_RX_PROP

DAEObject msim property key

See Also:

Constant Field Values

MSIM_ROOT_PROP

public static final java.lang.String MSIM_ROOT_PROP

DAEObject msim property key

See Also:

Constant Field Values

MAX_UNIQUE_NAME_TRIES

public static final int MAX_UNIQUE_NAME_TRIES

maximum tries to make a unique name

See Also:

Constant Field Values

daeUtils

protected static final vona.dae.util.DAEUtils daeUtils

for now use the singleton DAEUtils

unmarshaller

protected static final javax.xml.bind.Unmarshaller unmarshaller

unmarshaller for DAE MSim extras

nextAnonymousNameIndex

protected static int nextAnonymousNameIndex

used to generate unique names for DAE elements

nextUniqueLinkNameIndex

protected static int nextUniqueLinkNameIndex

used to generate unique names for DAE elements

nextUniqueJointNameIndex

protected static int nextUniqueJointNameIndex

used to generate unique names for DAE elements

nextUniqueWidgetNameIndex

protected static int nextUniqueWidgetNameIndex

used to generate unique names for DAE elements

Constructor Detail

DAELoader

public DAELoader()

Method Detail

loadFromDAE

public static Link loadFromDAE(Link linkageRoot,
               vona.dae.jaxb.dae.COLLADA dae,
               java.lang.String daeRoot,
               boolean loadGeometries)

Load a Linkage sub-tree from a COLLADA visual scene graph.

The COLLADA scene graph could have been umarshalled via a call to DAEUtils.unmarshalDAE(URL).

See MSim-COLLADA Model Correspondence in the class header doc for details of how the COLLADA structure is mapped to an MSim Linkage. The particular COLLADA structure that is loaded is identified by daeRoot, which if non-null must be one of the following:

• a relative COLLADA sidref within the "scene" element resolving to the "instance_visual_scene" or to a "node" therein
• an absolute COLLADA sidref resolving to a "node", "visual_scene", or "node" or "instance_node" therein, in a library

If daeRoot is null and there is at least one "instance_visual_scene" then the load proceeds as if daeRoot resolved to it. Otherwise, nothing is loaded.

linkageRoot is the MSim Link that will correspond to daeRoot. A warning will be issued and nothing will be loaded if any of the following hold:

• daeRoot fails to resolve to a COLLADA element as described above
• the element to which daeRoot resolved contains a COLLADA "extra" element with profile=MSim "technique" with a child other than "msim_link"
• linkageRoot was not passed as null, and the element to which daeRoot resolved contains a COLLADA "extra" element with profile=MSim "technique" that has "msim_link/ground_link" descendants (which would indicate that the passed linkageRoot should be the ground link of a sublinkage, but linkage membership of an msim LinkageNode is currently immutable)

Parameters:

linkageRoot - the attach point for the new sub-tree, or null to create a new root Link in the top-level Linkage

dae - the root node of the COLLADA document, not null

daeRoot - see above

loadGeometries - whether to map COLLADA geometries to Link user Widgets, if not they are ignored

Returns:

linkageRoot, which may be freshly consed if it was passed as null, or null if it was passed as null and daeRoot failed to resolve to a useful DAE root element (see above)

loadFromDAE

public static Link loadFromDAE(Link linkageRoot,
               vona.dae.jaxb.dae.COLLADA dae,
               java.lang.String daeRoot)

loadFromDAE(Link, COLLADA, String, boolean), loading geometries.

loadFromDAE

public static Link loadFromDAE(vona.dae.jaxb.dae.COLLADA dae,
               java.lang.String daeRoot)

loadFromDAE(Link, COLLADA, String, boolean), loading geometries and consing a new linkage root.

loadFromDAE

public static Link loadFromDAE(vona.dae.jaxb.dae.COLLADA dae)

loadFromDAE(Link, COLLADA, String, boolean), loading geometries, consing a new linkage root, and inferring the DAE root.

loadLinkFromDAE

protected static Link loadLinkFromDAE(Link link,
                   vona.dae.util.DAEObject source,
                   Link parentLink,
                   boolean loadGeoms,
                   java.util.List<DAELoader.LatentClosure> latentClosures)

Load an MSim Link from a DAE element.

link is consed (unless passed as non-null) and configured to match source. The parent joint of link is also consed if necessary according to the following rules:

• if no DAEMSimLink "extra" is present, and link is not the root of the MSim-DAE correspondence tree (which is indicated by the presence of MSIM_ROOT_PROP set on source), then the parent joint is a Joint.Type.GENERAL tree joint with identity child-to-mobility and mobility transforms, and mobility-to-parent set equal to the rigid part of the pose of source with respect to its parent
• if a DAEMSimLink "extra" is present but does not contain a DAEMSimJoint as DAEMSimLink.parentJoint, then link is a root (no parent joint other than its root joint), with the exception that the link at the root of the MSim-DAE correspondence tree, if not internally consed, will keep its original parent joint
• if a DAEMSimLink "extra" is present with a non-null DAEMSimLink.parentJoint, then a parent tree joint is consed/configured with the indicated settings.

Once link and its parent have been set up, this method recurs on the children of link. DAE "instance_geometry" children, which are terminal, are loaded as MSim user link widgets iff loadGeoms is set. DAE "node" and the referents of "instance_node" children are loaded recursively unless they contain an "extra" with a DAEMSimUserSubframe or DAEMSimClosure. The latter two cases, both also terminal, induce loading of a user subframe on link or a latent closure parented to link (and added to latentClosures).

Parameters:

link - the link to load into, or null to cons

source - the DAE element which corresponds to link, either a DAE "node" (NodeType) or a DAE "visual_scene" (VisualSceneType). If an MSim DAE "extra" is included (see getExtra(vona.dae.util.DAEObject)) then it must be a DAEMSimLink. source is considered to be the root of the MSim-DAE correspondence tree iff the property MSIM_ROOT_PROP is set on it, which has implications for how the parent joint of link may be configured as described above

parentLink - the parent link of the parent joint of link, or null if unknown (this could happen in the unusual case of a link with a dangling parent joint); if null then the ground link of the linkage containing link is used

loadGeoms - whether to load DAE "instance_geometry" (if source is a "node") as MSim user link widgets

latentClosures - any closure joints induced by the DAE structure are collected here for attachment at the end of the loading process

Returns:

link, which may be freshly consed, or even null if passed as null and problems were encountered before it could be consed

loadChildFromDAE

protected static void loadChildFromDAE(vona.dae.jaxb.dae.NodeType source,
                    Link parent,
                    boolean loadGeoms,
                    java.util.List<DAELoader.LatentClosure> latentClosures)

Load a COLLADA "node" child.

Parameters:

source - the child node, which will be loaded as either an MSim Link (if no DAEMSimExtra is present or if the extra is a DAEMSimLink), and MSim link user subframe (if a DAEMSimUserSubframe is present), or a (latent) MSim closure Joint (if a DAEMSimClosure is present)

parent - the MSim link corresponding to the parent of this node

loadGeoms - whether to load DAE "instance_geometry" as MSim user link widgets

latentClosures - the collection of DAELoader.LatentClosures

getExtra

public static DAEMSimExtra getExtra(vona.dae.util.DAEObject obj)

Unmarshal the first DAEMSimExtra in an DAEMSimExtra.MSIM_PROFILE DAE "technique" child of an "extra" child of obj, if any.

Current impl only checks for extra under COLLADA "node" and "visual_scene" elements (return will be null otherwise).

The set of types of MSim extra elements is read from DAEMSimExtra.MSIM_EXTRAS.

Once unmarshalled, the extra is stored as the MSIM_EXTRA_PROP property on obj.

getName

public static java.lang.String getName(vona.dae.util.DAEObject obj)

Resolve (or create) an MSim name for obj.

Once computed, the name is stored as the MSIM_NAME_PROP property on obj.

This method does not ensure the name is unique. Names are made unique as necessary when they are assigned in-context.

getRX

public static vona.math.RX getRX(vona.dae.util.DAEObject obj)

Resolve (or create) an MSim RX for obj.

The RX is identity except in the case that obj is a COLLADA "node", in which case it is the rigid part of the node's relative transform from its parent.

Once computed, the RX is stored as the MSIM_RX_PROP property on obj.