Rusfort/Asset-Frameworker
1
0
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects 3 Releases Wiki Activity

Token-based output support - needs testing

Browse Source
This commit is contained in:
Rusfort
2025-05-04 15:54:59 +02:00
parent 6b704c561a
commit 0a3100d448
13 changed files with 880 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
Documentation/01_User_Guide/04_Configuration_and_Presets.md
View File

@@ -44,4 +44,14 @@ Preset files define supplier-specific rules for interpreting asset source files.
When processing assets, you must specify which preset to use. The tool then loads the core settings from `config/app_settings.json` and merges them with the rules from the selected preset to determine how to process the input.
A template preset file (`presets/_template.json`) is provided as a base for creating new presets.
A template preset file (`presets/_template.json`) is provided as a base for creating new presets.
## Global Output Path Configuration
The structure and naming of the output files generated by the tool are now controlled by two global settings defined exclusively in `config/app_settings.json`:
* `OUTPUT_DIRECTORY_PATTERN`: Defines the directory structure where processed assets will be saved.
* `OUTPUT_FILENAME_PATTERN`: Defines the naming convention for the individual output files within the generated directory.
**Important:** These settings are global and apply to all processing tasks, regardless of the selected preset. They are **not** part of individual preset files and cannot be modified using the Preset Editor. You can view and edit these patterns in the main application preferences (**Edit** -> **Preferences...**).
These patterns use special tokens (e.g., `[assetname]`, `[maptype]`) that are replaced with actual values during processing. For a detailed explanation of how these patterns work together, the available tokens, and examples, please refer to the [Output Structure](./09_Output_Structure.md) section of the User Guide.

59
Documentation/01_User_Guide/09_Output_Structure.md
View File

@@ -2,20 +2,65 @@
This document describes the directory structure and contents of the processed assets generated by the Asset Processor Tool.
Processed assets are saved to: `<output_base_directory>/<supplier_name>/<asset_name>/`
Processed assets are saved to a location determined by two global settings defined in `config/app_settings.json`:
* `<output_base_directory>`: The base output directory configured in `config.py` or specified via CLI/GUI.
* `<supplier_name>`: The name of the asset supplier, determined from the preset used.
* `<asset_name>`: The name of the processed asset, determined from the source filename based on preset rules.
* `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., `AssetName_Color_4K.png`, `AssetName_NRM_2K.exr`). These are the resized, format-converted, and bit-depth adjusted texture files.
* Merged texture maps (e.g., `AssetName_NRMRGH_4K.png`). These are maps created by combining channels from different source maps based on the configured merge rules.
* 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 that were not classified as maps or models but were explicitly marked to be moved to the extra directory based on preset rules (e.g., previews, documentation files).
* `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).