Scene DOM

Work with XML documents. More...

Functions
newPaths	AppendPathAttributes (basePath, names)
	Copy a Scene DOM path and add attribute path parts.
newElement	CreateElementChild (element, name, id, where)
	Create a new document element.
elementStruct	ElementToStruct (element)
	Get a Matlab struct representation of an XML element.
idMap sortedKeys	GenerateSceneIDMap (docNode, excludePattern)
	Get uniquely identified XML document elements, and Scene DOM paths.
pathMap sortedKeys	GenerateScenePathMap (docNode, checkName, filterPattern, childPattern)
	Get many XML document nodes and Scene DOM paths.
authoringTool asset	GetColladaAuthorInfo (colladaFile)
	Get "authoring_tool" and "asset" elements from a Collad file.
lightType	GetColladaLightType (element)
	Get the type of a Collada document light element.
attributes names values	GetElementAttributes (element, name)
	Get the attributes owned by an XML document element.
children names	GetElementChildren (element, name, checkName, checkValue)
	Get the child elements of an XML document element.
nodePath	GetNodePath (node, checkName, childPattern)
	Make a Scene DOM path for an XML document element or attribute.
value	GetSceneValue (idMap, nodePath)
	Get the value of an element or attribute in an XML document.
	MergeAdjustments (sceneDoc, adjustmentsDoc, excludePattern)
	Merge an XML scene document with an adjustments document.
pathString	PathCellToString (pathCell)
	Convert a Scene DOM path cell array to the equivalent string.
pathCell	PathStringToCell (pathString)
	Convert a Scene DOM path string to the equivalent cell array.
pathPart	PrintPathPart (operator, name, checkName, checkValue)
	Print a formatted Scene DOM path.
docNode idMap	ReadSceneDOM (sceneFile, excludePattern)
	Read a scene XML document from file.
node	RemoveSceneNode (idMap, nodePath)
	Remove an element or attribute from an XML document.
	operator name checkName checkValue ScanPathPart (pathPart)
	Scan a Scene DOM path part for its components.
node	SearchScene (idMap, nodePath, isCreate)
	Find an element or attribute in an XML document.
oldValue	SetSceneValue (idMap, nodePath, value, isCreate, operator)
	Set the value of a document element or attribute.
reducedFile	WriteReducedColladaScene (colladaFile, reducedFile)
	Reduce a Collada scene file to basic geometry and materials.
	WriteSceneDOM (sceneFile, docNode)
	Write a scene XML document to file.

Detailed Description

Work with XML documents.

These functions are for reading and writing XML documents, like Collada scene files and renderer-native scene XML files. Notably, these functions deal with Scene DOM Paths.

Function Documentation

newPaths AppendPathAttributes	(	basePath	,
		names
	)

Copy a Scene DOM path and add attribute path parts.

Parameters

basePath	Scene DOM path to receive attributes
names	cell array of strings of attribute names

Copy the given basePath and append an attribute path part, once for each of the given names. basePath must be a scene DOM path that does not contain an attribute '.' operator. names must be a cell array of string attribute names to appent to basePath.

Returns a cell array of new scene DOM paths, one for each of the given names. Each new path begins with the given basePath, with one of the given attribute names appended as a path part.

Usage: newPaths = AppendPathAttributes(basePath, names)

newElement CreateElementChild	(	element	,
		name	,
		id	,
		where
	)

Create a new document element.

Parameters

element	document element to be the parent of the new element
name	string node name for the new element
id	string unique identifier for the new element (optional)
where	'first', 'last', or child element to replace (optional)

Create a new document element that is a child of the given element. element must be an element node from an scene document, as returned from SearchScene(). name must be the string node name for the new element.

If id is provided, the new element will have an "id" attribute with the value of id.

By default, appends the new element to the list of children of the given element. If toReplace is provided, it may be the string 'first', the string 'last', or an element object that is an existing shild of the given element. The new element will be located as follows:

• 'first' - new element will be prepended before other child elements
• 'last' - new element will be appended after other child elements
• existing child - new element will replace the given child element

Returns the new document element.

Usage: newElement = CreateElementChild(element, name, id, where)

elementStruct ElementToStruct

(

element

)

Get a Matlab struct representation of an XML element.

Parameters

element

XML element object

Builds a Matlab struct based on an XML element. The fields of the struct will have the same names as the element's child elements, and will contain nested structs that represent the children. A special "text" field will contain the text content of each element. A special "attributes" field will contain a struct with the attribute names and values for each element.

ElementToStruct() makes a "reasonable effort" to represent XML notes as Matlab structs, but it does not handle all cases. For example:

• Child elements named "text" or "attributes" will be overwritten by special fields.
• Child elements with duplicate names will be overwritten.
• Child elements with names that are not valid struct field names will be ignored, for example "#comment" of "#text".
• There's no StructToElement() function to convert a struct back to XML.
• It might perform badly for elements with many children (i.e. large documents).

Returns a Matlab struct that represents the given XML element.

Usage: elementStruct = ElementToStruct(element)

idMap sortedKeys GenerateSceneIDMap	(	docNode	,
		excludePattern
	)

Get uniquely identified XML document elements, and Scene DOM paths.

Parameters

docNode	XML document node object
excludePattern	regular expression to filter document elements

Traverses the XML DOM document represented by docNode, and builds a map to elements that have an "id" attribute.

Returns an "id map" that represents the same document as docNode. An id map is a containers.Map of document elements that have "id" attributes, with the id values as map keys. Nodes with id attributes often correspond to intuitive parts of a scene, like the camera, lights, shapes, and materials.

Also returns a cell array of element ids in depth first order. This is the order in which elements are encountered during document traversal. This should also be the top-down order of elements as the appear in the XML text file.

By default, returns all elements with id attributes. If excludePattern is provided, it must be a regular expression to match against element node names (note names are not the same as id attributes). Elements whose node names match excludePattern will not be added to the id map, even if they have an id attribute.

Usage: [idMap, sortedKeys] = GenerateSceneIDMap(docNode, excludePattern)

pathMap sortedKeys GenerateScenePathMap	(	docNode	,
		checkName	,
		filterPattern	,
		childPattern
	)

Get many XML document nodes and Scene DOM paths.

Parameters

docNode	XML document node object
checkName	name of attribute to include in the path
filterPattern	regular expression to filter document nodes
childPattern	regular expression to force child node behavior

Traverses the XML document represented by docNode, finding elements and attributes, and recording Scene DOM paths to each element or attribute.

Returns a "path map" that represents the same document as docNode. A path map is a containers.Map of all document elements and attributtes, with Scene DOM path strings as map keys.

Also returns a cell array of path strings in depth first order. This is the order in which elements and attributes are encountered during document traversal. This should also be the top-down order of elements as the appear in the XML text file.

By default, the Scene DOM paths refer only to element node names. Therefore, the paths may not be unique and some nodes will be ignored. If checkName is provided, it should be the name of an attribute that can disambiguate elements by its value. The attribute name and value will be included in the paths, for all objects that have the attribute.

A useful value for checkName might be 'id', 'sid', 'name', or 'semantic'. These attributes often distinguish similar nodes in Collada scene files and renderer adjustments files.

Also by default, all elements and attributes are included in the path map. If filterPattern is provided, it must be a regular expression to compare to each Scene DOM path string. Only nodes whose path strings match the filterPattern will be included in the path map.

Also by default, stops creating each Scene DOM path at the first node that has an "id" attribute. If childPattern is provided, it must be a regular expression to compare to node names (note names are not the samd as id attributes). Nodes whose node names match childPattern will allow path creation to continue, even if they have an id attribute.

Usage: [pathMap, sortedKeys] = GenerateScenePathMap(docNode, checkName, filterPattern, childPattern)

authoringTool asset GetColladaAuthorInfo

(

colladaFile

)

Get "authoring_tool" and "asset" elements from a Collad file.

Parameters

colladaFile

file name or path of a Collada scene file

Reads the Collada document in the given colladaFile and retrieves the authoring_tool and asset elements that describe how the file was created. authoring_tool should be a string that describes the modeling application, for example "Blender 2.69.0 r60991". asset should be a struct miscellaneous authoring info, such as the authoring_tool, creation date, unit of distance, etc.

authoring_tools and assed elements should be present in Collada files, according to the Collada 1.4 schema: http://www.khronos.org/collada/ http://www.khronos.org/files/collada_reference_card_1_4.pdf

Returns the string authoring_tool element value and struct representation of the entire asset element.

Usage: [authoringTool, asset] = GetColladaAuthorInfo(colladaFile)

lightType GetColladaLightType

(

element

)

Get the type of a Collada document light element.

Parameters

element

a light element from a Collada document

Determines the type of the given Collada document light element, based on the elements "technique_common" child element. The type of light may be "ambient", "directional", "point", or "spot". See http://www.khronos.org/collada/ for more about the Collada XML schema and lights.

Returns the string node name that determines the light type, either "ambient", "directional", "point", or "spot". If element is not a Collada light element, or is not a known type of light, returns ''.

Usage: lightType = GetColladaLightType(element)

attributes names values GetElementAttributes	(	element	,
		name
	)

Get the attributes owned by an XML document element.

Parameters

element	XML document element object
name	string name of an attribute (optional)

Get the attributes owned by an XML document element, if any.

element must be an element node from an XML document, as returned from GetSceneNode().

By default, returns a cell array of all attribute nodes, a cell array of strings of corresponding attribute names, and a cell array of strings of corresponding attribute values.

If name is provided, searches for a single attribute with the given name. If such an attribute is found, returns the single attribute object, string name, and string value. If no such attribute attribute is fouund, returns empty arrays.

Usage: [attributes, names, values] = GetElementAttributes(element, name)

children names GetElementChildren	(	element	,
		name	,
		checkName	,
		checkValue
	)

Get the child elements of an XML document element.

Parameters

element	XML document element object
name	string name of child elements (optional)
checkName	child attribute name to check (optional)
checkValue	child attribute value to check (optional)

Gets the children an XML document element, if any.

element must be an element from an XML document, as returned from GetSceneNode().

By default, returns a cell array of all the document elements that are children of the given element. Also returns a cell array of strings of all child element names.

If name is provided, searches only for child elements that have the node name name.

If name, checkName and checkValue are provided, searches for a single child element that has the node name name, and has an attribute with the name checkName and value equal to checkValue. If such a child element is found, returns the single child element and string name. Otherwise, returns empty values.

Usage: [children, names] = GetElementChildren(element, name, checkName, checkValue)

nodePath GetNodePath	(	node	,
		checkName	,
		childPattern
	)

Make a Scene DOM path for an XML document element or attribute.

Parameters

node	XML document element or attribute object
checkName	name of attribute to include in the path
childPattern	regular expression to force child node behavior

Create a Scene DOM path for the given XML document element or attribute.

By default, creates a Scene DOM path that only uses element names. If checkName is provided, it must the string name of an attribute to "check". For elements in the path that have an attribute with the given checkName, the name and value will be included in the path.

Also by default, stops creating a Scene DOM path at the first node that has an id attribute. If childPattern is provided, it must be a regular expression to compare to node names. Nodes whose names match childPattern will allow path creation to continue, even if they have an id attribute.

Returns a Scene DOM path cell array for the given node.

See the RenderToolbox3 wiki for more about Scene DOM paths.

Usage: nodePath = GetNodePath(node, checkName, childPattern)

value GetSceneValue	(	idMap	,
		nodePath
	)

Get the value of an element or attribute in an XML document.

Parameters

idMap	"id map" that represents an XML document
nodePath	Scene DOM path within the XML document

Gets the value of the element or attribute within the XML document represented by idMap, at the given nodePath.

idMap must be an "id map" that represents an XML document, as returned from ReadSceneDOM().

nodePath must be a scene DOM path as returned from GetNodePath().

Returns the string value of the element or attribute, or '' if there is no such element or attribute.

Usage: value = GetSceneValue(idMap, nodePath)

MergeAdjustments	(	sceneDoc	,
		adjustmentsDoc	,
		excludePattern
	)

Merge an XML scene document with an adjustments document.

Parameters

sceneDoc	document node that represents a scene file
adjustmentsDoc	document node that represents an adjustments file
excludePattern	regular expression to filter adjustments elements

Merge scene node values from the document represented by adjustmentsDoc into the document represented by sceneDoc. Nodes that exist in both documents will have their values set to the values in the adjustments document. Nodes that don't exist in the scene document will be created as needed.

sceneDoc adjustmentsDoc must be XML document nodes as returned from ReadSceneDOM(). sceneDoc may be a Collada parent scene file, a Mitsuba-native xml-file, or a RenderToolbox3 PBRT-XML file. adjustmentsSoc shouls use the same format as sceneDoc, and should contain elements that supplement or replace elements in sceneDoc.

Nodes in the adjustment file are matched with nodes in the scene file using the id attribute. A node in the adjustments file with the node name "merge" will merge values and attributes with the matching nodes in the scene file, with the adjustments nodes taking precidence. Other nodes will replace the matching node in the scene file.

By default, merges all nodes from adjustmentsDoc, in depth first order. If excludePattern is provided, it must be a regular expression to match against element node names (node names are not the same as id attributes). Elements whose node names match excludePattern will not be merged.

Usage: MergeAdjustments(sceneDoc, adjustmentsDoc, excludePattern)

pathString PathCellToString

(

pathCell

)

Convert a Scene DOM path cell array to the equivalent string.

Parameters

pathCell

Scene DOM path cell array

Returns a Scene DOM path string that is equivalent to the given pathCell. If pathCell is already a string, returns it as-is.

Usage: pathString = PathCellToString(pathCell)

pathCell PathStringToCell

(

pathString

)

Convert a Scene DOM path string to the equivalent cell array.

Parameters

pathString

Scene DOM path string

Returns a Scene DOM path cell array that is equivalent to the given pathString. If pathString is already a cell array, returns it as-is.

Usage: pathCell = PathStringToCell(pathString)

pathPart PrintPathPart	(	operator	,
		name	,
		checkName	,
		checkValue
	)

Print a formatted Scene DOM path.

Parameters

operator	string Scene DOM path operator
name	string Scene DOM node name (optional)
checkName	string Scene DOM check name (optional)
checkValue	string Scene DOM check value (optional)

Print a formatted path part, with the given operator, and optional name, checkName, and checkValue.

Returns a single formatted Scene DOM path part string.

Usage: pathPart = PrintPathPart(operator, name, checkName, checkValue)

docNode idMap ReadSceneDOM	(	sceneFile	,
		excludePattern
	)

Read a scene XML document from file.

Parameters

sceneFile	file name or path to read
excludePattern	regular expression to filter document elements

Read the given XML sceneFile (.dae or .xml). The sceneFile should be a Collada scene file, or a renderer adjustments file. Collada is is an XML-based format for exchanging 3D models and assets. Renderer Adjustments Files introduce scene elements that Collada doesn't know about.

Returns an XML Document Object Model (DOM) document node. DOM is a programmatic interface for XML files that takes advantage of XML document structure and takes care of reading and writing files.

Also returns an "id map" that represent the document in terms of elements that have unique identifiers (id attributes). If excludePattern is provided, it must be a regular expression to match against element node names. Elements whose names match excludePattern will not be added to the id map.

Usage: [docNode, idMap] = ReadSceneDOM(sceneFile, excludePattern)

node RemoveSceneNode	(	idMap	,
		nodePath
	)

Remove an element or attribute from an XML document.

Parameters

idMap	"id map" that represents an XML document
nodePath	Scene DOM path within the XML document

Remove the element or attribute from the XML document represented by idMap, at the given nodePath.

idMap must be an "id map" that represents an XML document, as returned from ReadSceneDOM().

nodePath must be a Scene DOM path as returned from GetNodePath().

Returns the element or attribute that was removed, or [] if there is no element or attribute the given nodePath.

Usage: node = RemoveSceneNode(idMap, nodePath)

operator name checkName checkValue ScanPathPart

(

pathPart

)

Scan a Scene DOM path part for its components.

Parameters

pathPart

one part of a Scene DOM path

Parse the given Scene DOM pathPart into its operator node name, check-name, and check-value (if any).

pathPart must be one element from a Scene DOM path cell array. See GetScenePath() for mode about scene paths.

Returns the string operator node name, check-name, and check-value. If any of these components is missing, returns '' instead.

Usage: [operator, name, checkName, checkValue] = ScanPathPart(pathPart)

node SearchScene	(	idMap	,
		nodePath	,
		isCreate
	)

Find an element or attribute in an XML document.

Parameters

idMap	"id map" that represents an XML document
nodePath	Scene DOM path within the XML document
isCreate	whether to create new document nodes (optional)

Traverse the XML document represented by the given idMap, following the given nodePath Scene DOM path.

idMap must be an "id map" that represents an XML document, as returned from ReadSceneDOM().

nodePath must be a Scene DOM path as returned from GetNodePath().

Returns the first document element or attribute that matches nodePath. By default, if there is no such element or attribute, returns []. If isCreate is provided and true, creates element or attribute as necessary to satisfy nodePath.

Usage: node = SearchScene(idMap, nodePath, isCreate)

oldValue SetSceneValue	(	idMap	,
		nodePath	,
		value	,
		isCreate	,
		operator
	)

Set the value of a document element or attribute.

Parameters

idMap	"id map" that represents an XML document
nodePath	Scene DOM path within the XML document
value	string value to assign to an element or attribute
isCreate	whether to create new document nodes (optional)
operator	how to apply value (optional

Sets the value of the element or attribute within the XML document represented by idMap, at the given nodePath.

idMap must be an "id map" that represents an XML document, as returned from ReadSceneDOM().

nodePath must be a scene DOM path as returned from GetNodePath().

value must be a string value to assign to the element or attribute.

By default, if there is no element or attribute at the given nodePath, prints a warning. If isCreate is provided and true, creates missing elements and attributes as needed to satisfy nodePath, then sets the given value.

By default, assigns value to the element or attribute at nodePath. If operator is provided, it may specify a different way to apply value:

• '=' - assign value to the element or attribute
• '+=' - add value to the element or attribute value
• '-=' - subtract value from the element or attribute value
• '*=' - multiply value with the element or attribute value
• '/=' - divide the element or attribute value by value

Attempts to convert between string and numeric values as necessary.

Returns the old value at the given nodePath, if any.

Usage: oldValue = SetSceneValue(idMap, nodePath, value, isCreate, operator)

reducedFile WriteReducedColladaScene	(	colladaFile	,
		reducedFile
	)

Reduce a Collada scene file to basic geometry and materials.

Parameters

colladaFile	file name or path of a Collada scene file
reducedFile	file name or path of the new, reuduced scene

Traverses the Collada document in the given colladaFile and writes a new, reduced version of the document, with the given reducedFile name. The reduced document will contain all of the basic scene elements including cameras, some types of lights, and geometry. It will not contain fancier scene elemnets like textured materials, animations, controllers, and physics.

Attempts to obey the Collada 1.4 schema, so that the new reducedFile will be a valid Collada file. See http://www.khronos.org/collada/ for more about the Collada XML schema. This cheat sheet is especially useful: http://www.khronos.org/files/collada_reference_card_1_4.pdf

Returns the name of the new, reduced scene file.

Usage: reducedFile = WriteReducedColladaScene(colladaFile, reducedFile)

WriteSceneDOM	(	sceneFile	,
		docNode
	)

Write a scene XML document to file.

Parameters

sceneFile	file name or path to write
docNode	XML document node object

Write a new XML scene file with the given sceneFile name (which use the extension .dae or .xml). The given domDoc must be an XML document node as returned from ReadSceneDOM().

Usage: WriteSceneDOM(sceneFile, docNode)