Difference between revisions of "Using URIs in COLLADA"

From COLLADA Public Wiki
Jump to: navigation, search
(a little editing to make generic.)
(shove in material from DOM guide: Resolving URIs...first pass saving)
Line 1: Line 1:
'''URIs''' in [[COLLADA]] and the [[COLLADA DOM]] must be of the correct standard format to work correctly.
+
'''URIs''' in [[COLLADA]] must be of the correct standard format to work correctly.
  
 +
 +
== info 1==
 +
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:
 +
file:///c:/path/document.dae#Geo_01
 +
is a URI that references a file named <code>document.dae</code> on the localhost found in <code>c:/path</code>.
 +
 +
The ''fragment'' portion is used to identify elements by using their "id" attribute. The previous example references an element with an id "Geo_01".
 +
 +
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.
 +
 +
Examples of relative path URIs:
 +
./path/document.dae
 +
../../../path/document.dae#elementID
 +
document.dae#Geo_01
 +
 +
A Windows absolute path must be preceded by a forward slash character '/'. An example:
 +
/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.
 +
 +
Assuming a base URI of
 +
file:///c:/A/B/C/D/doc.dae
 +
here are some examples of how the following URIs will 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
 +
|}
 +
 +
 +
'''''Note:''' Windows file paths '''are not''' proper URIs!''
 +
 +
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.
 +
== 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.
 
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.
  
Line 9: Line 69:
 
  Linux absolute path    /folder/file.dae                file:///folder/file.dae
 
  Linux absolute path    /folder/file.dae                file:///folder/file.dae
 
  Linux relative path    ../folder/file.dae              ../folder/file.dae
 
  Linux relative path    ../folder/file.dae              ../folder/file.dae
 +
 +
==See also==
 +
* [[DOM resolver subsystem]]
 +
* [[DOM URI resolver system]]
 +
* [[DOM guide: Resolving URIs]]
  
 
[[Category:COLLADA terminology]]
 
[[Category:COLLADA terminology]]

Revision as of 01:56, 24 May 2007

URIs in COLLADA must be of the correct standard format to work correctly.


info 1

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 localhost is used. For example:

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

is a URI that references a file named document.dae on the localhost found in c:/path.

The fragment portion is used to identify elements by using their "id" attribute. The previous example references an element with an id "Geo_01".

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.

Examples of relative path URIs:

./path/document.dae
../../../path/document.dae#elementID
document.dae#Geo_01

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

/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.

Assuming a base URI of

file:///c:/A/B/C/D/doc.dae

here are some examples of how the following URIs will be 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


Note: Windows file paths are not proper URIs!

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.

info 3

A common mistake is to use a Windows or Linux file path. Both COLLADA and the COLLADA DOM use URIs exclusively to reference resources or files. A file path needs to be converted to a 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
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