Rusfort/Asset-Frameworker
1
0
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects 3 Releases Wiki Activity
Asset-Frameworker/Documentation/01_User_Guide/09_Output_Structure.md

5.4 KiB
Raw Blame History

User Guide: Output Structure

This document describes the directory structure and contents of the processed assets generated by the Asset Processor Tool.

Processed assets are saved to a location determined by two global settings defined in config/app_settings.json:

  • OUTPUT_DIRECTORY_PATTERN: Defines the directory structure within the Base Output Directory.
  • OUTPUT_FILENAME_PATTERN: Defines the naming convention for individual files within the directory created by OUTPUT_DIRECTORY_PATTERN.

These patterns use special tokens (explained below) that are replaced with actual values during processing. You can configure these patterns via the main application preferences (Edit -> Preferences... -> Output & Naming tab). They are global settings and are not part of individual presets.

Available Tokens

The following tokens can be used in both OUTPUT_DIRECTORY_PATTERN and OUTPUT_FILENAME_PATTERN. Note that some tokens make more sense in one pattern than the other (e.g., [maptype] and [ext] are typically used in the filename pattern).

  • [Assettype]: The type of asset (e.g., Texture, Model, Surface).
  • [supplier]: The supplier name (from the preset, e.g., Poliigon).
  • [assetname]: The main asset name (e.g., RustyMetalPanel).
  • [resolution]: Texture resolution (e.g., 1k, 2k, 4k).
  • [ext]: The output file extension (e.g., png, jpg, exr). (Primarily for filename pattern)
  • [IncrementingValue] or [####]: A numerical value that increments based on existing directories matching the OUTPUT_DIRECTORY_PATTERN in the output base path. The number of # characters determines the zero-padding (e.g., [###] -> 001, 002). If [IncrementingValue] is used, it defaults to 4 digits of padding (0001, 0002).
  • [Date]: Current date (YYYYMMDD).
  • [Time]: Current time (HHMMSS).
  • [Sha5]: The first 5 characters of the SHA-256 hash of the original input source file (e.g., the source zip archive).
  • [ApplicationPath]: Absolute path to the application directory.
  • [maptype]: Specific map type (e.g., Albedo, Normal). (Primarily for filename pattern)
  • [dimensions]: Pixel dimensions (e.g., 2048x2048).
  • [bitdepth]: Output bit depth (e.g., 8bit, 16bit).
  • [category]: Asset category determined by preset rules.
  • [archetype]: Asset archetype determined by preset rules.
  • [variant]: Asset variant identifier determined by preset rules.
  • [source_filename]: The original filename of the source file being processed.
  • [source_basename]: The original filename without the extension.
  • [source_dirname]: The directory containing the original source file.

Example Output Paths

The final output path is constructed by combining the Base Output Directory (set in Preferences or via CLI) with the results of the two patterns.

Example 1:

  • Base Output Directory: /home/user/ProcessedAssets
  • OUTPUT_DIRECTORY_PATTERN: [supplier]/[assetname]/[resolution]
  • OUTPUT_FILENAME_PATTERN: [assetname]_[maptype]_[resolution].[ext]
  • Resulting Path for an Albedo map: /home/user/ProcessedAssets/Poliigon/WoodFloor001/4k/WoodFloor001_Albedo_4k.png

Example 2:

  • Base Output Directory: Output (relative path)
  • OUTPUT_DIRECTORY_PATTERN: [Assettype]/[category]/[assetname]
  • OUTPUT_FILENAME_PATTERN: [maptype].[ext]
  • Resulting Path for a Normal map: Output/Texture/Wood/WoodFloor001/Normal.exr

The <output_base_directory> (the root folder where processing output starts) is configured separately via the GUI (Edit -> Preferences... -> Output & Naming tab -> Base Output Directory) or the --output CLI argument. The OUTPUT_DIRECTORY_PATTERN defines the structure within this base directory, and OUTPUT_FILENAME_PATTERN defines the filenames within that structure.

Contents of Each Asset Directory

Each asset directory contains the following:

  • Processed texture maps (e.g., WoodFloor_Albedo_4k.png, MetalPanel_Normal_2k.exr). The exact filenames depend on the OUTPUT_FILENAME_PATTERN. These are the resized, format-converted, and bit-depth adjusted texture files.
  • Merged texture maps (e.g., WoodFloor_Combined_4k.png). The exact filenames depend on the OUTPUT_FILENAME_PATTERN. These are maps created by combining channels from different source maps based on the configured merge rules.
  • Model files (if present in the source asset).
  • metadata.json: A JSON file containing detailed information about the asset and the processing that was performed. This includes details about the maps, resolutions, formats, bit depths, merged map details, calculated image statistics, aspect ratio change information, asset category and archetype, the source preset used, and a list of ignored source files. This file is intended for use by downstream tools or scripts (like the Blender integration scripts).
  • EXTRA/ (subdirectory): Contains source files not classified as maps or models but marked as "EXTRA" by preset rules (e.g., previews, documentation). These files are placed in an EXTRA folder within the directory generated by OUTPUT_DIRECTORY_PATTERN.
  • Unrecognised/ (subdirectory): Contains source files that were not classified as maps, models, or explicitly marked as extra, and were not ignored.
  • Ignored/ (subdirectory): Contains source files that were explicitly ignored during processing (e.g., an 8-bit Normal map when a 16-bit variant exists and is prioritized).