Difference between revisions of "Using URIs in COLLADA"

From COLLADA Public Wiki
Jump to: navigation, search
(shove in material from DOM guide: Resolving URIs...first pass saving)
(reorg & edit some... more still needed.)
Line 1: Line 1:
'''URIs''' in [[COLLADA]] must be of the correct standard format to work correctly.
+
[[COLLADA]] uses '''[http://en.wikipedia.org/wiki/Uniform_Resource_Identifier 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.
  
 +
== URI syntax==
  
== info 1==
+
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 base URI syntax is:
 
scheme://authority/filepath?query#fragment
 
  
An ''absolute URI'' contains a scheme and an authority. If the authority is left empty than <code>localhost</code> is used. For example:
+
The basic URI syntax is:
file:///c:/path/document.dae#Geo_01
+
''scheme''://''authority''/''filepath''?''query''#''fragment''
is a URI that references a file named <code>document.dae</code> on the localhost found in <code>c:/path</code>.
+
 
 +
URIs are either absolute or relative:
 +
*An ''absolute URI'' contains a ''scheme'' and an ''authority''.  
 +
*A ''relative URI'' is any URI that does not contain a ''scheme'' and ''authority''. A relative URI can be a relative path, an absolute path, or just a fragment.
  
The ''fragment'' portion is used to identify elements by using their "id" attribute. The previous example references an element with an id "Geo_01".
+
The ''fragment'' portion identifies elements by using their ''id'' attribute. This attribute references an element that can be found within the same document as the URI. An example of this:
 +
#redMaterial
  
A ''relative URI'' is any URI that does not contain a scheme and authority. A relative URI can be a relative path, an absolute path, or just a fragment.
+
For example:
 +
file:///c:/path/document.dae#Geo_01
 +
is an absolute URI that references a file named <code>document.dae</code> on the localhost found in <code>c:/path</code>; it references an element with an ''id'' of "Geo_01".
  
 
Examples of relative path URIs:
 
Examples of relative path URIs:
Line 19: Line 24:
 
  document.dae#Geo_01
 
  document.dae#Geo_01
  
A Windows absolute path must be preceded by a forward slash character '/'. An example:
+
== Normalizing relative URIs==
/c:/path/document.dae#Light01
 
 
 
A fragment identifier references an element that can be found within the same document as the URI. An example of this:
 
#redMaterial
 
 
 
== info 2==
 
 
A base URI is needed to normalize relative URIs. Absolute URIs do not require a separate base URI.
 
A base URI is needed to normalize relative URIs. Absolute URIs do not require a separate base URI.
  
 
Assuming a base URI of
 
Assuming a base URI of
 
  file:///c:/A/B/C/D/doc.dae
 
  file:///c:/A/B/C/D/doc.dae
here are some examples of how the following URIs will be normalized:
+
here are some examples of how the following URIs are normalized:
 
{| border=1 cellspacing=0 cellpadding=4
 
{| border=1 cellspacing=0 cellpadding=4
 
|-
 
|-
Line 56: Line 55:
 
|}
 
|}
  
 +
==Windows paths and URIs==
 +
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.''
  
'''''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.
  
Note also that only the slash (/) character is used as a path delimeter. 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 following are some examples of converting a file path to a URI.
== info 3==
 
A common mistake is to use a Windows or Linux file path. Both COLLADA and the COLLADA DOM use [http://en.wikipedia.org/wiki/Uniform_Resource_Identifier URIs] exclusively to reference resources or files. 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. 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
+
!Example Description||File Path||URI
UNC path               \\remoteMachine\folder\file.dae  file://///remoteMachine/folder/file.dae
+
|-
Linux absolute path   /folder/file.dae                 file:///folder/file.dae
+
|Windows absolute path ||
Linux relative path   ../folder/file.dae               ../folder/file.dae
+
  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==

Revision as of 02:22, 24 May 2007

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.

URI syntax

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? ))


The basic URI syntax is:

scheme://authority/filepath?query#fragment

URIs are either absolute or relative:

  • An absolute URI contains a scheme and an authority.
  • A relative URI is any URI that does not contain a scheme and authority. A relative URI can be a relative path, an absolute path, or just a fragment.

The fragment portion identifies elements by using their id attribute. This attribute references an element that can be found within the same document as the URI. An example of this:

#redMaterial

For example:

file:///c:/path/document.dae#Geo_01

is an absolute URI that references a file named document.dae on the localhost found in c:/path; it references an element with an id of "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. 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 the following URIs are normalized:

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

Windows paths and URIs

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.

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