# 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, `OUTPUT_DIRECTORY_PATTERN` and `OUTPUT_FILENAME_PATTERN`, defined in `config/app_settings.json`. These settings can be overridden by the user via `config/user_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]`: The standardized map type identifier (e.g., `COL` for Color/Albedo, `NRM` for Normal, `RGH` for Roughness). This is derived from the `standard_type` defined in the application's `FILE_TYPE_DEFINITIONS` (managed in `config/file_type_definitions.json` via the Definitions Editor) and may include a variant suffix if applicable. (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...** -> **General** tab -> **Output Base 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.
    *   **LOWRES Variants:** If the "Low-Resolution Fallback" feature is enabled and a source image's dimensions are below the configured threshold, an additional variant with "LOWRES" as its resolution token (e.g., `MyTexture_COL_LOWRES.png`) will be saved. This variant uses the original dimensions of the source image.
*   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, and for roughness maps, a `derived_from_gloss_filename: true` flag if it was inverted from an original gloss map), 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).