Difference between revisions of "Using URIs in COLLADA"

From COLLADA Public Wiki
Jump to: navigation, search
m (URI moved to Using URIs in COLLADA: better description of current content)
m (Native Paths versus URIs)
 
(25 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[COLLADA]] uses '''URIs''' exclusively to reference resources or files. The URIs  must be of the correct standard format to work correctly.  A common mistake is to use Windows or Linux paths as URIs. This article describes the correct standardized URI and gives examples.
+
{{tutorials}}
  
==How URIs are used 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 locate and retrieve the resource that the URI identifies. This article describes how to use 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==
+
==URIs in COLLADA==
  
A file path needs to be converted to a [http://en.wikipedia.org/wiki/URI_scheme file scheme] URI before being passed to the COLLADA DOM. {{editor|what=This also applies to COLLADA, not just the DOM, right?}}
+
The COLLADA schema uses the [http://www.w3.org/TR/xmlschema-2/#anyURI XML Schema xs:anyURI] type to represent URIs. This XML Schema type describes absolute and relative URI, including URI references, so you can use any of these forms in a COLLADA document.
  
The basic URI file scheme syntax is:
+
Some examples of URI usage in COLLADA include
''scheme''://''authority''/''filepath''?''query''#''fragment''
+
* The ''target'' attribute of <instance_material> elements
 +
* The ''url'' attribute on <instance_geometry>, <instance_node>, and <instance_effect> elements
 +
* The <image>/<init_from> element
  
URIs are either absolute or relative:
+
For URIs that reference COLLADA elements (such as the ''url'' attribute on the <instance_geometry> element), the URI fragment portion identifies the element by its ''id'' attribute. Because COLLADA documents are XML documents, the syntax for the URI fragment is defined by the [http://www.w3.org/TR/xptr/ XML Pointer Language (XPointer)] and the [http://www.w3.org/TR/xptr-framework/#shorthand shorthand pointer] is the most common usage. An example of this:
*An ''absolute URI'' contains a scheme and an authority.  
+
<instance_geometry url="file:///models/car.dae#carGeometry" />
*A ''relative URI'' is any URI that does not contain both a scheme and an authority. A relative URI can be a relative path, an absolute path, or just a fragment.
+
This <instance_geometry> references the <geometry> element whose ''id'' is <code>carGeometry</code> in the document <code>file:///models/car.dae</code>.
  
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:
+
The following example uses a relative URI reference, which must be resolved to an absolute URI before the application can obtain the referenced <geometry> element:
  #redMaterial
+
  <instance_geometry url="../car.dae#carGeometry" />
  
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".
+
==Base URIs in a COLLADA document==
file:///c:/path/document.dae#Geo_01
+
To resolve relative references, a base URI is needed. In COLLADA, the base URI can be specified in the root <COLLADA> element:
 +
<COLLADA xmlns=<nowiki>"http://www.collada.org/2005/11/COLLADASchema"</nowiki> 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's URI according to the rules defined in [http://www.apps.ietf.org/rfc/rfc3986.html#sec-5.1 RFC 3986 section 5.1]. For example, if the document's URI is <code>file:///car.dae</code>, then the URI parsing logic in your software uses that as the base URI to resolve any relative references in the document.
  
Examples of relative path URIs:
+
It's important to note that a relative reference cannot indicate a change to the scheme part of the base URI.
./path/document.dae
 
../../../path/document.dae#elementID
 
document.dae#Geo_01
 
  
== Normalizing relative URIs==
+
==Native Paths versus URIs==
A base URI is needed to normalize relative URIs (turn them into absolute URIs). Absolute URIs do not require a separate base URI.
+
''An ordinary Windows or Linux native filesystem path is not a valid URI!''
  
Assuming a base URI of
+
A '''file-scheme URI''' (see [http://tools.ietf.org/html/rfc1738#section-5 RFC 1738 section 5]) represents a file on the local machine. File paths need to be converted to file-scheme URIs before they can be used properly by URI aware (i.e. COLLADA) applications. If the base URI's scheme is '''file''' (which is often the case), then you can use a relative reference to the file instead of specifying a full file-scheme URI. When the reference is resolved by the application, it becomes a valid file-scheme URI.
file:///c:/A/B/C/D/doc.dae
+
 
here are some examples of how URIs would be normalized:
+
The following examples specify 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.
{| border=1 cellspacing=0 cellpadding=4
+
 
 +
{|
 
|-
 
|-
!Original URI||Normalized URI
+
!Example Description||File Path||URI Reference
 
|-
 
|-
 +
|Windows absolute path ||
 +
C:\folder\image.tga
 
|
 
|
  ./path/document.dae                 
+
  /C:/folder/image.tga
 +
|-
 +
| Windows relative path ||
 +
..\folder\image.tga 
 
|
 
|
  file:///c:/A/B/C/D/path/document.dae
+
  ../folder/image.tga
 
|-
 
|-
 +
|Linux absolute path ||
 +
/folder/image.tga
 
|
 
|
  ../../../path/document.dae#elementID 
+
  /folder/image.tga
|
 
  file:///A/path/document.dae#elementID
 
 
|-
 
|-
 +
|Linux relative path ||
 +
../folder/image.tga
 
|
 
|
  /c:/path/document.dae#Light01       
+
  ../folder/image.tga
|
 
file:///c:/path/document.dae#Light01
 
 
|-
 
|-
 +
| UNC path ||
 +
\\remoteMachine\folder\image.tga
 
|  
 
|  
  c:/path/document.dae                 
+
  file://///remoteMachine/folder/image.tga
|
 
  file:///c:/A/B/C/D/c:/path/document.dae
 
 
|}
 
|}
  
==Paths versus URIs==
+
In particular, note that "\" characters convert to "/", and that Windows volume specifiers (e.g. "C:") must be prepended with "/" to become proper URI absolute-path references.
 
 
===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.''
+
So, in a COLLADA document you could write
  
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.
+
<image>
 +
  <init_from>../folder/image.tga</init_from>
 +
</image>
  
===Examples===
+
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. More examples of how relative references are resolved can be found in [http://www.apps.ietf.org/rfc/rfc3986.html#sec-5.4 RFC 3986 section 5.4].
  
The following are some examples of converting a file path to a URI.
+
As the last example in the table shows, an exception is made for Windows UNC paths. In theory, you could convert the UNC file path <code>\\remoteMachine\folder\image.tga</code> to the 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 that the base URI is <code>file:///C:/models/maya/car.dae</code>, this resolves to the URI <code>file://remoteMachine/folder/image.tga</code>.
  
{|
+
However, many XML parsers can't work correctly with such URIs. One example is libxml, which the COLLADA DOM uses 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, with which most XML libraries can work correctly.
|-
 
!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==
 
==See also==
Line 105: Line 82:
 
* [[DOM guide: Resolving URIs]]
 
* [[DOM guide: Resolving URIs]]
  
==External links==
+
[[Category:COLLADA tutorials]]
* [http://en.wikipedia.org/wiki/Uniform_Resource_Identifier Definition of URI]
 
 
 
[[Category:COLLADA terminology]]
 

Latest revision as of 00:00, 7 May 2011

Tutorials
This article is one several tutorials, guides, and annotated examples available in this wiki.
Multipage tutorials:  • COLLADA DOM user guide
Shorter how-tos:  • Using accessors  • Schema validation • Using URIs
 • Various annotated examples

Instructions for adding a tutorial

[[Category: ]]


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 locate and retrieve the resource that the URI identifies. This article describes how to use URIs in COLLADA.

URIs in COLLADA

The COLLADA schema uses the XML Schema xs:anyURI type to represent URIs. This XML Schema type describes absolute and relative URI, including URI references, so you can use any of these forms in a COLLADA document.

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 (such as the url attribute on the <instance_geometry> element), the URI fragment portion identifies the element by its id attribute. Because COLLADA documents are XML documents, the syntax for the URI fragment is defined by the XML Pointer Language (XPointer) and the shorthand pointer is the most common usage. 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.

The following example uses a relative URI reference, which must be resolved to an absolute URI before the application can obtain the referenced <geometry> element:

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

Base URIs in a COLLADA document

To resolve relative 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's URI according to the rules defined in RFC 3986 section 5.1. For example, if the document's URI is file:///car.dae, then the URI parsing logic in your software uses that as the base URI to resolve any relative references in the document.

It's important to note that a relative reference cannot indicate a change to the scheme part of the base URI.

Native Paths versus URIs

An ordinary Windows or Linux native filesystem path is not a valid URI!

A file-scheme URI (see RFC 1738 section 5) represents a file on the local machine. File paths need to be converted to file-scheme URIs before they can be used properly by URI aware (i.e. COLLADA) applications. If the base URI's scheme is file (which is often the case), then you can use a relative reference to the file instead of specifying a full file-scheme URI. When the reference is resolved by the application, it becomes a valid file-scheme URI.

The following examples specify 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 convert to "/", and that Windows volume specifiers (e.g. "C:") must be prepended with "/" to become proper URI absolute-path references.

So, in a COLLADA document you 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. More examples of how relative references are resolved can be found in RFC 3986 section 5.4.

As the last example in the table shows, an exception is made for Windows UNC paths. In theory, you could convert the UNC file path \\remoteMachine\folder\image.tga to the 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 that the base URI is file:///C:/models/maya/car.dae, this resolves to the URI file://remoteMachine/folder/image.tga.

However, many XML parsers can't work correctly with such URIs. One example is libxml, which the COLLADA DOM uses 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, with which most XML libraries can work correctly.

See also