Difference between revisions of "Using URIs in COLLADA"

From COLLADA Public Wiki
Jump to: navigation, search
(merge steve's changes that I stepped on)
Line 1: Line 1:
[[COLLADA]] uses only '''[[URI]]s''' to reference resources or files. A URI must be formatted properly for the application to find the resource the URI identifies. This article describes how to use URIs in COLLADA.
+
'''[[URI]]s''' are used extensively in [[COLLADA document]]s to reference other COLLADA elements or external resources such as texture files, shader source code, and so on. A URI must be formatted properly for the application to find the resource the URI identifies. This article describes how to use URIs in COLLADA.
  
==How URIs are used in COLLADA==
+
==URIs in COLLADA==
URIs are used extensively in [[COLLADA document]]s to reference other COLLADA elements or external resources, for example, texture files, shader source code, and so on.
 
  
== URI syntax==
+
The COLLADA schema uses the [http://www.w3.org/TR/xmlschema-2/#anyURI xs:anyURI] type to represent URIs. xs:anyURI allows for URI references in addition to URIs, so you can use either a URI or a relative URI reference.
  
A file path needs to be converted to a [[URI|file scheme URI]] before being passed to the COLLADA DOM. {{editor|what=This also applies to COLLADA, not just the DOM, right?}}
+
For URIs that reference COLLADA elements (like the ''url'' attribute on the <instance_geometry> element), the ''fragment'' portion identifies the element by its ''id'' attribute. An example of this:
 +
<instance_geometry url="file:///models/car.dae#carGeometry />
 +
This <instance_geometry> references the <geometry> element whose ID is <code>carGeometry</code> in the document <code>file:///models/car.dae</code>.
 +
<instance_geometry url="../car.dae#carGeometry />
 +
In this example a relative reference is used. It'll need to be resolved to a URI before the application can obtain the referenced <geometry> element.
  
The basic URI file scheme syntax is:
+
==Base URIs in a COLLADA document==
''scheme''://''authority''/''filepath''?''query''#''fragment''
+
To resolve relative URI references, a base URI is needed. In COLLADA, the base URI can be specified in the root <COLLADA> element:
 
+
  <COLLADA xmlns="http://www.collada.org/2005/11/COLLADASchema" version="1.4.1"
In COLLADA documents, the ''fragment'' portion identifies elements by their COLLADA ''id'' attribute.  The ''id'' attribute references an element that can be found within the same document as the URI. An example of this:
+
          xml:base="file:///home/sthomas/models/duck.dae">
  #redMaterial
+
If the ''xml:base'' attribute isn't specified, then the base URI is the document URI. So if the document URI is "file:///car.dae", then that'll be the base URI used to resolve any relative references in the document.
 
 
Example of an absolute URI that references a file named <code>document.dae</code> on the localhost found in <code>c:/path</code>; it refers to an element with an ''id'' of "Geo_01".
 
file:///c:/path/document.dae#Geo_01
 
 
 
Examples of relative path URIs:
 
./path/document.dae
 
../../../path/document.dae#elementID
 
document.dae#Geo_01
 
 
 
== Normalizing relative URIs==
 
A base URI is needed to normalize relative URIs (turn them into absolute URIs). Absolute URIs do not require a separate base URI.
 
 
 
Assuming a base URI of
 
file:///c:/A/B/C/D/doc.dae
 
here are some examples of how URIs would be normalized:
 
{| border=1 cellspacing=0 cellpadding=4
 
|-
 
!Original URI||Normalized URI
 
|-
 
|
 
./path/document.dae                 
 
|
 
file:///c:/A/B/C/D/path/document.dae
 
|-
 
|
 
../../../path/document.dae#elementID 
 
|
 
  file:///A/path/document.dae#elementID
 
|-
 
|
 
/c:/path/document.dae#Light01       
 
|
 
file:///c:/path/document.dae#Light01
 
|-
 
|
 
c:/path/document.dae                 
 
|
 
  file:///c:/A/B/C/D/c:/path/document.dae
 
|}
 
  
 
==Paths versus URIs==
 
==Paths versus URIs==
A common mistake is to use Windows or Linux paths as URIs.
+
A common mistake is to use Windows or Linux paths as URIs. A file path needs to be converted to a [[URI|file scheme URI]] before being passed to the COLLADA DOM. {{editor|what=This also applies to COLLADA, not just the DOM, right?}}
  
 
===Windows paths===
 
===Windows paths===

Revision as of 22:53, 25 May 2007

URIs are used extensively in COLLADA documents to reference other COLLADA elements or external resources such as texture files, shader source code, and so on. A URI must be formatted properly for the application to find the resource the URI identifies. This article describes how to use URIs in COLLADA.

URIs in COLLADA

The COLLADA schema uses the xs:anyURI type to represent URIs. xs:anyURI allows for URI references in addition to URIs, so you can use either a URI or a relative URI reference.

For URIs that reference COLLADA elements (like the url attribute on the <instance_geometry> element), the fragment portion identifies the element by its id attribute. An example of this:

<instance_geometry url="file:///models/car.dae#carGeometry />

This <instance_geometry> references the <geometry> element whose ID is carGeometry in the document file:///models/car.dae.

<instance_geometry url="../car.dae#carGeometry />

In this example a relative reference is used. It'll need to be resolved to a URI before the application can obtain the referenced <geometry> element.

Base URIs in a COLLADA document

To resolve relative URI references, a base URI is needed. In COLLADA, the base URI can be specified in the root <COLLADA> element:

<COLLADA xmlns="http://www.collada.org/2005/11/COLLADASchema" version="1.4.1"
         xml:base="file:///home/sthomas/models/duck.dae">

If the xml:base attribute isn't specified, then the base URI is the document URI. So if the document URI is "file:///car.dae", then that'll be the base URI used to resolve any relative references in the document.

Paths versus URIs

A common mistake is to use Windows or Linux paths as URIs. A file path needs to be converted to a file scheme URI before being passed to the COLLADA DOM. ((EDITOR: This page needs the following improvement: This also applies to COLLADA, not just the DOM, right? ))


Windows paths

A Windows absolute path must be preceded by a forward slash character '/'. An example:

/c:/path/document.dae#Light01

Note: Windows file paths are not proper URIs.

Only the slash (/) character is used as a path delimeter in URIs. Windows uses the backslash (\) to delimit path segments. Using the backslash can result in incorrect URI processing. "A\B\C" is considered one path segment. If using "file:///A\B\C" as a base URI and trying to resolve "../doc.dae" the result will be "file:///doc.dae" and not "file:///A\B\doc.dae" as one might have expected.

Examples

The following are some examples of converting a file path to a URI.

Example Description File Path URI
Windows absolute path
C:\folder\file.dae 
file:///C:/folder/file.dae
Windows relative path
..\folder\file.dae  
../folder/file.dae
UNC path
\\remoteMachine\folder\file.dae 
file://///remoteMachine/folder/file.dae
Linux absolute path
/folder/file.dae 
file:///folder/file.dae
Linux relative path
../folder/file.dae
../folder/file.dae

See also