Initial commit

Documentation/01_User_Guide/01_Introduction.md

@@ -0,0 +1,15 @@
+# User Guide: Introduction
+
+This document provides an introduction to the Asset Processor Tool for users.
+
+## Purpose
+
+This tool processes 3D asset source files (texture sets, models, etc., provided as ZIP archives or folders) into a standardized library format. It uses configurable presets to interpret different asset sources and automates tasks like file classification, image resizing, channel merging, and metadata generation.
+
+## Interfaces
+
+The tool offers both a Graphical User Interface (GUI) for interactive use and a Command-Line Interface (CLI) for batch processing and scripting. It also includes a Directory Monitor for automated processing of assets dropped into a watched folder, and optional integration with Blender for automated material/nodegroup creation.
+
+## Scope
+
+This documentation focuses on how to use the Asset Processor Tool. It assumes familiarity with basic file system operations and the concepts of 3D assets like texture sets and models. Details on environment setup, dependency installation, building the project, or deployment procedures are covered in other sections or assume standard practices.

Documentation/01_User_Guide/02_Features.md

@@ -0,0 +1,44 @@
+# User Guide: Features
+
+This document outlines the key features of the Asset Processor Tool.
+
+## Core Processing & Classification
+
+*   **Preset-Driven:** Uses JSON presets (`presets/`) to define rules for different asset suppliers (e.g., `Poliigon.json`).
+*   **Multi-Asset Input Handling:** Correctly identifies and processes multiple distinct assets contained within a single input `.zip`, `.rar`, `.7z` archive, or folder, creating separate outputs for each.
+*   **File Classification:** Automatically identifies map types (Color, Normal, Roughness, etc.), models, explicitly marked extra files, and unrecognised files based on preset rules.
+    *   **Variant Handling:** Map types listed in `RESPECT_VARIANT_MAP_TYPES` (in `config.py`, e.g., `"COL"`) always receive a numeric suffix (`-1`, `-2`, etc.). Numbering priority uses preset keyword order first, then alphabetical filename sorting as a tie-breaker. Other map types never receive a suffix.
+    *   **16-bit Prioritization:** Correctly identifies and prioritizes 16-bit variants defined in preset `bit_depth_variants` (e.g., `*_NRM16.tif`), ignoring the corresponding 8-bit version (marked as `Ignored` in GUI).
+*   **Map Processing:**
+    *   Resizes texture maps to configured resolutions (e.g., 4K, 2K, 1K), avoiding upscaling.
+    *   Handles Glossiness map inversion to Roughness.
+    *   Applies bit-depth rules (`respect` source or `force_8bit`).
+    *   Saves maps in appropriate formats (JPG, PNG, EXR) based on complex rules involving map type (`FORCE_LOSSLESS_MAP_TYPES`), resolution (`RESOLUTION_THRESHOLD_FOR_JPG`), bit depth, and source format.
+    *   Calculates basic image statistics (Min/Max/Mean) for a reference resolution.
+    *   Calculates and stores the relative aspect ratio change string in metadata (e.g., `EVEN`, `X150`, `Y125`).
+*   **Channel Merging:** Combines channels from different maps into packed textures (e.g., NRMRGH) based on preset rules (`MAP_MERGE_RULES` in `config.py`).
+*   **Metadata Generation:** Creates a `metadata.json` file for each asset containing details about maps, category, archetype, aspect ratio change, processing settings, etc.
+*   **Output Organization:** Creates a clean, structured output directory (`<output_base>/<supplier>/<asset_name>/`).
+*   **Optimized Classification:** Pre-compiles regular expressions from presets for faster file identification.
+
+## Interface & Automation
+
+*   **Dual Interface:** Provides both a user-friendly GUI and a powerful CLI.
+*   **Parallel Processing:** Utilizes multiple CPU cores for faster processing (configurable via `--workers` in CLI or GUI control).
+*   **Skip/Overwrite:** Can skip processing if the output already exists or force reprocessing (`--overwrite` flag / checkbox).
+*   **Directory Monitor:** Includes `monitor.py` script for automated processing of assets dropped into a watched folder.
+*   **Responsive GUI:** Uses background threads (`QThread`, `ProcessPoolExecutor`, `ThreadPoolExecutor`) to keep the UI responsive during intensive operations.
+*   **GUI Features:**
+    *   Drag-and-drop input (ZIPs / folders).
+    *   Integrated preset editor panel.
+    *   Configurable output directory field with browse button.
+    *   Enhanced live preview table showing predicted file status.
+    *   Toggleable preview mode (detailed file list vs simple asset list).
+    *   Toggleable log console panel.
+    *   Progress bar, cancellation button, clear queue button.
+
+## Integration
+
+*   **Blender Integration:** Optionally runs Blender scripts (`create_nodegroups.py`, `create_materials.py`) after asset processing to automate node group and material creation in specified `.blend` files. Available via both CLI and GUI.
+    *   **GUI Controls:** Checkbox to enable/disable Blender integration and input fields with browse buttons for target `.blend` files.
+*   **Docker Support:** Includes a `Dockerfile` for containerized execution.

Documentation/01_User_Guide/03_Installation.md

@@ -0,0 +1,37 @@
+# User Guide: Installation
+
+This document details the requirements and steps for installing the Asset Processor Tool.
+
+## Requirements
+
+*   Python 3.8 +
+*   Required Python Packages (see `requirements.txt`):
+    *   `opencv-python` (image processing)
+    *   `numpy` (numerical operations)
+    *   `py7zr` (7z archive support)
+    *   `rarfile` (RAR archive support)
+    *   `PySide6` (for the GUI only)
+    *   `watchdog` (for the directory monitor)
+*   Optional Python Packages:
+    *   `OpenEXR` (improved `.exr` handling, recommended if processing EXR sources)
+*   **Blender:** A working installation is required for optional Blender integration. Configure the path in `config.py` or ensure it's in the system PATH.
+
+## Installation Steps
+
+1.  Navigate to the project root directory in your terminal.
+2.  Install core dependencies using pip:
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+3.  If you plan to use the GUI, ensure `PySide6` is installed. It might be included in `requirements.txt`, or install separately:
+
+    ```bash
+    pip install PySide6
+    ```
+
+4.  If you plan to use the directory monitor script, ensure `watchdog` is installed. It might be included in `requirements.txt`, or install separately:
+
+    ```bash
+    pip install watchdog

Documentation/01_User_Guide/04_Configuration_and_Presets.md

@@ -0,0 +1,27 @@
+# User Guide: Configuration and Presets
+
+This document explains how to configure the Asset Processor Tool and use presets.
+
+## Core Settings (`config.py`)
+
+The tool's behavior is controlled by core settings defined in `config.py`. While primarily for developers, some settings are important for users to be aware of:
+
+*   `OUTPUT_BASE_DIR`: The default root directory where processed assets will be saved.
+*   `IMAGE_RESOULTIONS`: Defines the target resolutions for processed texture maps (e.g., 4K, 2K).
+*   `BLENDER_EXECUTABLE_PATH`: The path to your Blender installation, required for optional Blender integration.
+*   Other settings control aspects like default asset category, filename patterns, map merge rules, and output formats.
+
+These settings can often be overridden via the GUI or CLI arguments.
+
+## Preset Files (`presets/*.json`)
+
+Preset files define supplier-specific rules for interpreting asset source files. They are crucial for the tool to correctly classify files and process assets from different sources.
+
+*   Presets are located in the `presets/` directory.
+*   Each preset is a JSON file named after the supplier (e.g., `Poliigon.json`).
+*   Presets contain rules based on filename patterns and keywords to identify map types, models, and other files.
+*   They also define how variants (like different resolutions or bit depths) are handled and how asset names and categories are determined from the source filename.
+
+When processing assets, you must specify which preset to use. The tool then loads the core settings from `config.py` 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.

Documentation/01_User_Guide/05_Usage_GUI.md

@@ -0,0 +1,35 @@
+# User Guide: Usage - Graphical User Interface (GUI)
+
+This document explains how to use the Asset Processor Tool's Graphical User Interface.
+
+## Running the GUI
+
+From the project root directory, run the following command:
+
+```bash
+python -m gui.main_window
+```
+
+## Interface Overview
+
+*   **Menu Bar:** The "View" menu allows you to toggle the visibility of the Log Console and the Detailed File Preview.
+*   **Preset Editor Panel (Left):**
+    *   **Optional Log Console:** Displays application logs (toggle via View menu).
+    *   **Preset List:** Create, delete, load, edit, and save presets. On startup, the "-- Select a Preset --" item is explicitly selected. You must select a specific preset from this list to load it into the editor below, enable the detailed file preview, and enable the "Start Processing" button.
+    *   **Preset Editor Tabs:** Edit the details of the selected preset.
+*   **Processing Panel (Right):**
+    *   **Preset Selector:** Choose the preset to use for *processing* the current queue.
+    *   **Output Directory:** Set the output path (defaults to `config.py`, use "Browse...")
+    *   **Drag and Drop Area:** Add asset `.zip`, `.rar`, `.7z` files, or folders by dragging and dropping them here.
+    *   **Preview Table:** Shows queued assets. Initially, this area displays a message prompting you to select a preset. Once a preset is selected from the Preset List, the detailed file preview will load here. The mode of the preview depends on the "View" menu:
+    *   **Detailed Preview (Default):** Lists all files, predicted status (`Mapped`, `Model`, `Extra`, `Unrecognised`, `Ignored`, `Error`), output name, etc., based on the selected *processing* preset. Text colors are applied to cells based on the status of the individual file they represent. Rows use alternating background colors per asset group for visual separation.
+    *   **Simple View (Preview Disabled):** Lists only top-level input asset paths.
+*   **Progress Bar:** Shows overall processing progress.
+*   **Blender Post-Processing:** Checkbox to enable Blender scripts. If enabled, shows fields and browse buttons for target `.blend` files (defaults from `config.py`).
+    *   **Options & Controls (Bottom):**
+        *   `Overwrite Existing`: Checkbox to force reprocessing.
+        *   `Workers`: Spinbox for concurrent processes.
+        *   `Clear Queue`: Button to clear the queue and preview.
+        *   `Start Processing`: Button to start processing the queue. This button is disabled until a valid preset is selected from the Preset List.
+        *   `Cancel`: Button to attempt stopping processing.
+*   **Status Bar:** Displays current status, errors, and completion messages.

Documentation/01_User_Guide/06_Usage_CLI.md

@@ -0,0 +1,30 @@
+# User Guide: Usage - Command-Line Interface (CLI)
+
+This document explains how to use the Asset Processor Tool's Command-Line Interface.
+
+## Running the CLI
+
+From the project root directory, run the following command:
+
+```bash
+python main.py [OPTIONS] INPUT_PATH [INPUT_PATH ...]
+```
+
+## Arguments
+
+*   `INPUT_PATH`: One or more paths to input `.zip`, `.rar`, `.7z` files, or folders.
+
+## Options
+
+*   `-p PRESET`, `--preset PRESET`: **(Required)** Name of the preset (e.g., `Poliigon`).
+*   `-o OUTPUT_DIR`, `--output-dir OUTPUT_DIR`: Override `OUTPUT_BASE_DIR` from `config.py`.
+*   `-w WORKERS`, `--workers WORKERS`: Number of parallel processes (default: auto).
+*   `--overwrite`: Force reprocessing and overwrite existing output.
+*   `-v`, `--verbose`: Enable detailed DEBUG level logging.
+*   `--nodegroup-blend NODEGROUP_BLEND`: Path to `.blend` for node groups. Triggers script if provided. Overrides `config.py`.
+*   `--materials-blend MATERIALS_BLEND`: Path to `.blend` for materials. Triggers script if provided. Overrides `config.py`.
+
+## Example
+
+```bash
+python main.py "C:/Downloads/WoodFine001.zip" -p Poliigon -o "G:/Assets/Processed" --workers 4 --overwrite --nodegroup-blend "G:/Blender/Libraries/NodeGroups.blend" --materials-blend "G:/Blender/Libraries/Materials.blend"

Documentation/01_User_Guide/07_Usage_Monitor.md

@@ -0,0 +1,34 @@
+# User Guide: Usage - Directory Monitor (Automated Processing)
+
+This document explains how to use the Asset Processor Tool's Directory Monitor for automated processing.
+
+## Running the Monitor
+
+From the project root directory, run the following command:
+
+```bash
+python monitor.py
+```
+
+## Functionality
+
+The monitor script uses the `watchdog` library to continuously monitor a specified input directory for new `.zip`, `.rar`, or `.7z` files. When a new supported archive file is detected, it expects the filename to follow the format `[preset]_filename.zip`, `[preset]_filename.rar`, or `[preset]_filename.7z`. It extracts the preset name from the filename and automatically processes the asset using that preset. After processing, the source archive file is moved to either a 'processed' directory (on success or skip) or an 'error' directory (on failure or invalid preset).
+
+**Note:** The directory monitor does *not* currently support optional Blender script execution (this is only available via the CLI or GUI).
+
+## Configuration (Environment Variables)
+
+The monitor's behavior is configured using environment variables:
+
+*   `INPUT_DIR`: The directory to monitor (default: `/data/input`).
+*   `OUTPUT_DIR`: The base output directory (default: `/data/output`).
+*   `PROCESSED_DIR`: Directory for successful source ZIPs (default: `/data/processed`).
+*   `ERROR_DIR`: Directory for failed source ZIPs (default: `/data/error`).
+*   `LOG_LEVEL`: Logging verbosity (`INFO`, `DEBUG`) (default: `INFO`).
+*   `POLL_INTERVAL`: Check frequency (seconds) (default: `5`).
+*   `PROCESS_DELAY`: Delay before processing detected file (seconds) (default: `2`).
+*   `NUM_WORKERS`: Number of parallel workers (default: auto).
+
+## Output
+
+The monitor logs messages to the console. It creates processed assets in the `OUTPUT_DIR` and moves the source `.zip` file as described above.

Documentation/01_User_Guide/08_Usage_Blender.md

@@ -0,0 +1,37 @@
+# User Guide: Usage - Blender Integration
+
+This document explains how to use the optional Blender integration feature of the Asset Processor Tool.
+
+## Overview
+
+The Asset Processor Tool can optionally run Blender scripts after processing assets. These scripts automate the creation of PBR node groups and materials in specified `.blend` files, linking to the processed textures. This feature is available when using the tool via the Command-Line Interface (CLI) or the Graphical User Interface (GUI).
+
+## How it Works (User Perspective)
+
+When the Blender integration is enabled and configured, the Asset Processor Tool will:
+
+1.  Process the input assets and generate the output files, including the `metadata.json` file for each asset.
+2.  Execute Blender in the background using the specified Blender executable path.
+3.  Run the `blenderscripts/create_nodegroups.py` script within Blender, passing the path to the processed asset's output directory and the target `.blend` file for node groups. This script reads the `metadata.json` and creates/updates PBR node groups in the target `.blend` file.
+4.  If configured, execute the `blenderscripts/create_materials.py` script within Blender, passing the path to the processed asset's output directory, the target `.blend` file for materials, and the `.blend` file containing the node groups. This script reads the `metadata.json`, creates/updates materials in the target materials `.blend` file, and links them to the node groups created in the node group `.blend` file.
+
+## Enabling and Configuring Blender Integration
+
+### In the GUI
+
+*   Locate the "Blender Post-Processing" section in the Processing Panel.
+*   Check the box to enable the Blender integration.
+*   Input fields and browse buttons will appear for specifying the target `.blend` files for Node Groups and Materials. These fields will default to the paths configured in `config.py`.
+
+### In the CLI
+
+*   Use the `--nodegroup-blend` option followed by the path to the target `.blend` file for node groups.
+*   Use the `--materials-blend` option followed by the path to the target `.blend` file for materials.
+
+Providing either of these options in the CLI will trigger the respective Blender script execution after asset processing. These command-line options override the default paths set in `config.py`.
+
+## Requirements
+
+*   A working installation of Blender.
+*   The path to the Blender executable configured in `config.py` or accessible in your system's PATH.
+*   For the material creation script, the target `.blend` file must contain a template material named `Template_PBRMaterial` with a Group node labeled `PLACEHOLDER_NODE_LABEL` (as defined in `blenderscripts/create_materials.py`).

Documentation/01_User_Guide/09_Output_Structure.md

@@ -0,0 +1,21 @@
+# 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: `<output_base_directory>/<supplier_name>/<asset_name>/`
+
+*   `<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.
+
+## 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.
+*   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).
+*   `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).

Documentation/01_User_Guide/10_Docker.md

@@ -0,0 +1,34 @@
+# User Guide: Docker
+
+This document explains how to use the Asset Processor Tool with Docker.
+
+## Overview
+
+A `Dockerfile` and `requirements-docker.txt` are provided to allow you to build and run the Asset Processor Tool in a containerized environment. This is primarily intended for CLI or monitor usage.
+
+## Building the Docker Image
+
+From the project root directory, run the following command to build the Docker image:
+
+```bash
+docker build -t asset-processor-tool .
+```
+
+This command builds a Docker image named `asset-processor-tool` using the `Dockerfile` in the current directory.
+
+## Running the Docker Container
+
+You can run the Docker container using standard Docker commands. You will typically need to mount volumes to make your input assets and desired output directory accessible within the container.
+
+Here is an example run command (adjust volumes as needed):
+
+```bash
+docker run -v /path/to/your/inputs:/data/input -v /path/to/your/outputs:/data/output asset-processor-tool python main.py /data/input/YourAsset.zip -p YourPreset
+```
+
+*   `-v /path/to/your/inputs:/data/input`: This mounts your local input directory (`/path/to/your/inputs`) to the `/data/input` directory inside the container.
+*   `-v /path/to/your/outputs:/data/output`: This mounts your local output directory (`/path/to/your/outputs`) to the `/data/output` directory inside the container.
+*   `asset-processor-tool`: The name of the Docker image to run.
+*   `python main.py /data/input/YourAsset.zip -p YourPreset`: The command to execute inside the container. This example runs the CLI with a specific input file and preset, using the mounted input and output directories.
+
+Adjust the input file path (`/data/input/YourAsset.zip`) and preset name (`YourPreset`) as needed for your specific use case. You can also adapt the command to run the `monitor.py` script within the container.