Difference between revisions of "Using URIs in COLLADA"

From COLLADA Public Wiki
Jump to: navigation, search
(Paths versus URIs)
(Paths versus URIs)
Line 23: Line 23:
  
 
==Paths versus URIs==
 
==Paths versus URIs==
An ordinary Windows or Linux file path is not a valid URI. A file scheme URI is used to represent a file on the local machine. The file scheme is described at http://tools.ietf.org/html/rfc1738. File paths need to be converted to file scheme URIs before they can be used properly by COLLADA applications. If the base URI's scheme is ''file'' (which is usually the case), then you can use a relative reference to the file instead specifying a full file scheme URI. When the reference is resolved by the application it'll become a valid file scheme URI.
+
An ordinary Windows or Linux file path is not a valid URI. A file scheme URI is used to represent a file on the local machine. The file scheme is described at http://tools.ietf.org/html/rfc1738. File paths need to be converted to file scheme URIs before they can be used properly by COLLADA applications. If the base URI's scheme is ''file'' (which is usually the case), then you can use a relative reference to the file instead specifying a full file scheme URI. When the reference is resolved by the application it becomes a valid file scheme URI.
  
 
Below are some examples of specifying a file via a relative URI reference in COLLADA. These examples assume that the base URI's scheme is ''file'', otherwise the reference won't resolve correctly. You might use these examples in the <image>/<init_from> element to refer to an image file on disk.
 
Below are some examples of specifying a file via a relative URI reference in COLLADA. These examples assume that the base URI's scheme is ''file'', otherwise the reference won't resolve correctly. You might use these examples in the <image>/<init_from> element to refer to an image file on disk.
Line 40: Line 40:
 
|
 
|
 
  ../folder/image.tga
 
  ../folder/image.tga
|-
 
| UNC path ||
 
\\remoteMachine\folder\image.tga
 
|
 
file://///remoteMachine/folder/image.tga
 
 
|-
 
|-
 
|Linux absolute path ||
 
|Linux absolute path ||
Line 55: Line 50:
 
|
 
|
 
  ../folder/image.tga
 
  ../folder/image.tga
 +
|-
 +
| UNC path ||
 +
\\remoteMachine\folder\image.tga
 +
|
 +
file://///remoteMachine/folder/image.tga
 
|}
 
|}
  
Looking at the second example more closely, I could write
+
In particular, note that "\" characters get converted to "/", and that Windows-style "C:" specifiers must be prepended with a "/" to become a proper URI reference.
 +
 
 +
So in a COLLADA document I could write
  
 
  <image>
 
  <image>
Line 63: Line 65:
 
  </image>
 
  </image>
  
in my COLLADA document. Suppose the base URI is <code>file:///C:/models/maya/car.dae</code>. An application will resolve the relative reference against the base URI to get <code>file:///C:/models/folder/image.tga</code>, which is a valid file scheme URI.
+
Suppose the base URI is <code>file:///C:/models/maya/car.dae</code>. An application will resolve the relative reference against the base URI to get <code>file:///C:/models/folder/image.tga</code>, which is a valid file scheme URI.
 +
 
 +
As the last example in the table shows, a special exception needs to be made for Windows UNC paths. In theory, you could convert a UNC file path <code>\\remoteMachine\folder\image.tga</code> to a relative reference <code>//remoteMachine/folder/image.tga</code>. The spec calls this a ''network-path reference'' (as described [http://gbiv.com/protocols/uri/rfc/rfc3986.html#relative-ref here]). The authority is <code>remoteMachine</code> and the path is <code>/folder/image.tga</code>. Assuming the base URI is <code>file:///C:/models/maya/car.dae</code>, this would get resolved to the URI <code>file://remoteMachine/folder/image.tga</code>.
  
'''''Note:''' Windows file paths '''are not''' proper URI references. Only the slash (/) character is used as a path delimeter in URIs or URI references. 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.''
+
The problem is that many XML parsers aren't capable of working with such URIs correctly. One example is libxml, which is used by the COLLADA DOM to load COLLADA documents. Instead of specifying the UNC path as a URI reference, it's better to use a file scheme URI as shown in the table. Most XML libraries are able to work with such URIs correctly.
  
 
==See also==
 
==See also==

Revision as of 02:24, 26 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.

Some examples of URI usage in COLLADA include

  • The target attribute of <instance_material> elements
  • The url attribute on <instance_geometry>, <instance_node>, and <instance_effect> elements
  • The <image>/<init_from> element

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

An ordinary Windows or Linux file path is not a valid URI. A file scheme URI is used to represent a file on the local machine. The file scheme is described at http://tools.ietf.org/html/rfc1738. File paths need to be converted to file scheme URIs before they can be used properly by COLLADA applications. If the base URI's scheme is file (which is usually the case), then you can use a relative reference to the file instead specifying a full file scheme URI. When the reference is resolved by the application it becomes a valid file scheme URI.

Below are some examples of specifying a file via a relative URI reference in COLLADA. These examples assume that the base URI's scheme is file, otherwise the reference won't resolve correctly. You might use these examples in the <image>/<init_from> element to refer to an image file on disk.

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

In particular, note that "\" characters get converted to "/", and that Windows-style "C:" specifiers must be prepended with a "/" to become a proper URI reference.

So in a COLLADA document I could write

<image>
  <init_from>../folder/image.tga</init_from>
</image>

Suppose the base URI is file:///C:/models/maya/car.dae. An application will resolve the relative reference against the base URI to get file:///C:/models/folder/image.tga, which is a valid file scheme URI.

As the last example in the table shows, a special exception needs to be made for Windows UNC paths. In theory, you could convert a UNC file path \\remoteMachine\folder\image.tga to a relative reference //remoteMachine/folder/image.tga. The spec calls this a network-path reference (as described here). The authority is remoteMachine and the path is /folder/image.tga. Assuming the base URI is file:///C:/models/maya/car.dae, this would get resolved to the URI file://remoteMachine/folder/image.tga.

The problem is that many XML parsers aren't capable of working with such URIs correctly. One example is libxml, which is used by the COLLADA DOM to load COLLADA documents. Instead of specifying the UNC path as a URI reference, it's better to use a file scheme URI as shown in the table. Most XML libraries are able to work with such URIs correctly.

See also