Managing External Files
From K-3D
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:
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.