Managing External Files

From K-3D

Jump to: navigation, search

Overview

In K-3D, all but the most trivial of documents will reference external files - bitmap textures, shaders, linked geometry files, and-so-on. When you save your document, it will contain references (or "links") to those external files. Making references work correctly across multiple platforms and user environments is a surprisingly tricky task - this document describes current K-3D behavior in saving and loading references, so you can avoid pitfalls.

Plugins that reference external files will use the standard file browser control:

Image:External_file_reference.png

The browse (...) button is used to select external files. To the right of the browse button, a dropdown list displays the three reference types: absolute, relative and inline. These reference types control how K-3D stores references to external files.

Reference Types

Absolute

When K-3D stores an absolute reference, it stores the complete, fully-qualified path to the external file, including the root directory and - on multi-root operating systems such as Win32 - the root name:

Operating System External File Location K-3D Document Location K-3D Document Contents
GNU/Linux /home/bob/textures/my_logo.png /home/bob/scenes/flying_logo.k3d /home/bob/textures/my_logo.png
Win32 c:\textures\my_logo.png c:\scenes\flying_logo.k3d c:\textures\my_logo.png

Special Cases

  • If the path to the external resource points to a subdirectory of the K-3D share path, a relative reference will be stored instead. Rationale: the contents of the K-3D share path are intended to be shared among all K-3D installations, storing a relative reference ensures that the resource can be accessed on all platforms and hosts.

Pros

  • No matter where you move the K-3D document on your local machine, the external files can always be located when you reload it.

Cons

  • If you move your external files, they will not be located when you reload your K-3D document.
  • If you move your K-3D document to a different machine, the external files can only be located if they're in the exact same filesystem location when you reload your K-3D document.
  • If you move your K-3D document to a machine running a different operating system (e.g: if you saved it using GNU/Linux and are loading it using Win32), the external files cannot be located when you reload your K-3D document.

Relative

When K-3D stores a relative reference, it stores the path to the external file, relative to the directory containing the K-3D document:

Operating System External File Location K-3D Document Location K-3D Document Contents
GNU/Linux /home/bob/textures/my_logo.png /home/bob/scenes/flying_logo.k3d ../textures/my_logo.png
GNU/Linux /home/bob/scenes/flying_logo/textures/my_logo.png /home/bob/scenes/flying_logo/scene.k3d textures/my_logo.png
Win32 c:\textures\my_logo.png c:\scenes\flying_logo.k3d ..\textures\my_logo.png
Win32 z:\textures\my_logo.png c:\scenes\flying_logo.k3d z:\textures\my_logo.png

Special Cases

  • If the K-3D document and external resource reside on different trees in a multi-root operating system such as Win32, an absolute reference is saved.
  • If the external resource is within the K-3D share directory, the stored path will be relative to the share directory instead of the document. Rationale: this behavior ensures that documents that reference the contents of the share directory always work, even on different hosts or platforms.

Pros

  • You can move your K-3D document and external files on the local machine, as long as they move together and are in the same relative positions in the filesystem.
  • You can move your K-3D document and external files to another machine, as long as they move together and are in the same relative positions in the filesystem.
  • You can move your K-3D document and external files to a different operating system, as long as they move together and are in the same relative positions in the filesystem.

Cons

  • If you move your K-3D document without moving the external files to the same relative position, they will not be located when you load your document.
  • If you move your external files without moving the K-3D document to the same relative position, the external files will not be located when you load your document.

Inline

When K-3D stores an inline reference, it stores a copy of the external file in your K-3D document. When you load the document, the file is extracted from the K-3D document and stored in a temporary location on the filesystem. Any type of file can be stored in this way (including bitmaps and other binary files).

Pros

  • You can move the document at-will, to other filesystem locations, machines, or operating systems, and the external files will always be available.

Cons

  • Files stored inline take more space in your K-3D document than they would on-disk (they are encoded in the XML using base64, which requires 33% more space than the native file).
  • Some external files (such as shaders) may contain internal links to other external files; the code for storing inline files isn't aware of those relationships, in which case the inlined files will contain references to non-existent files when extracted on a different system.
Personal tools