{
    "sourceFile": "documentation.txt",
    "activeCommit": 0,
    "commits": [
        {
            "activePatchIndex": 3,
            "patches": [
                {
                    "date": 1745327520295,
                    "content": "Index: \n===================================================================\n--- \n+++ \n"
                },
                {
                    "date": 1745328737162,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -103,5 +103,166 @@\n *   **Error Handling:** Uses standard `try...except` blocks and defines some custom exceptions (e.g., `ConfigurationError`, `AssetProcessingError`).\r\n *   **Parallelism:** Uses `concurrent.futures.ProcessPoolExecutor` for CPU-bound tasks (asset processing).\r\n *   **GUI:** Uses `PySide6` (Qt for Python) with signals and slots for communication between UI elements and background threads (`QThread`).\r\n *   **Configuration:** Relies on Python modules (`config.py`) for core settings and JSON files (`Presets/`) for specific rule sets.\r\n-*   **File Paths:** Uses `pathlib.Path` for handling file system paths.\n\\ No newline at end of file\n+*   **File Paths:** Uses `pathlib.Path` for handling file system paths.\r\n+================================\r\n+Internal Details for Debugging\r\n+================================\r\n+\r\n+This section provides deeper technical details about the internal workings, intended to aid in debugging unexpected behavior.\r\n+\r\n+--------------------------------\r\n+7. Internal Logic & Algorithms\r\n+--------------------------------\r\n+\r\n+*   **Configuration Preparation (`Configuration` class in `configuration.py`):**\r\n+    *   Instantiated per preset (`__init__`).\r\n+    *   Loads core settings from `config.py` using `importlib.util`.\r\n+    *   Loads specified preset from `presets/{preset_name}.json`.\r\n+    *   Validates basic structure of loaded settings (`_validate_configs`), checking for required keys and basic types (e.g., `map_type_mapping` is a list of dicts).\r\n+    *   Compiles regex patterns (`_compile_regex_patterns`) from preset rules (extra, model, bit depth, map keywords) using `re.compile` (mostly case-insensitive) and stores them on the instance (e.g., `self.compiled_map_keyword_regex`). Uses `_fnmatch_to_regex` helper for basic wildcard conversion.\r\n+\r\n+*   **CLI Argument Parsing (`main.py:setup_arg_parser`):**\r\n+    *   Uses `argparse` to define and parse command-line arguments.\r\n+    *   Key arguments influencing flow: `--preset` (required), `--output-dir` (optional override), `--workers` (concurrency), `--overwrite` (force reprocessing), `--verbose` (logging level), `--nodegroup-blend`, `--materials-blend`.\r\n+    *   Calculates a default worker count based on `os.cpu_count()`.\r\n+\r\n+*   **Output Directory Resolution (`main.py:main`):**\r\n+    *   Determines the base output directory by checking `--output-dir` argument first, then falling back to `OUTPUT_BASE_DIR` from `config.py`.\r\n+    *   Resolves the path to an absolute path and ensures the directory exists (`Path.resolve()`, `Path.mkdir(parents=True, exist_ok=True)`).\r\n+\r\n+*   **Asset Processing (`AssetProcessor` class in `asset_processor.py`):**\r\n+    *   **Classification (`_inventory_and_classify_files`):**\r\n+        *   Multi-pass approach: Explicit Extra (regex) -> Models (regex) -> Potential Maps (keyword regex) -> Standalone 16-bit check (regex) -> Prioritize 16-bit variants -> Final Maps -> Remaining as Unrecognised (Extra).\r\n+        *   Uses compiled regex patterns provided by the `Configuration` object passed during initialization.\r\n+        *   Sorts potential map variants based on: 1. Preset rule index, 2. Keyword index within rule, 3. Alphabetical path. Suffixes (`-1`, `-2`) are assigned later per-asset based on this sort order and `RESPECT_VARIANT_MAP_TYPES`.\r\n+    *   **Map Processing (`_process_maps`):**\r\n+        *   Loads images using `cv2.imread` (flags: `IMREAD_UNCHANGED` or `IMREAD_GRAYSCALE`). Converts BGR to RGB if needed.\r\n+        *   Handles Gloss->Roughness inversion: Loads gloss, inverts using float math (`1.0 - img/norm`), stores as float32 with original dtype. Prioritizes gloss source if both gloss and native rough exist.\r\n+        *   Resizes using `cv2.resize` (interpolation: `INTER_LANCZOS4` for downscale, `INTER_CUBIC` for potential same-size/upscale - though upscaling is generally avoided by checks).\r\n+        *   Determines output format based on hierarchy: `FORCE_LOSSLESS_MAP_TYPES` > `RESOLUTION_THRESHOLD_FOR_JPG` > Input format priority (TIF/EXR often lead to lossless) > Configured defaults (`OUTPUT_FORMAT_16BIT_PRIMARY`, `OUTPUT_FORMAT_8BIT`).\r\n+        *   Determines output bit depth based on `MAP_BIT_DEPTH_RULES` ('respect' vs 'force_8bit').\r\n+        *   Converts dtype before saving (e.g., float to uint8/uint16 using scaling factors 255.0/65535.0).\r\n+        *   Calculates stats (`_calculate_image_stats`) on normalized float64 data for a specific resolution (`CALCULATE_STATS_RESOLUTION`).\r\n+        *   Calculates aspect ratio string (`_normalize_aspect_ratio_change`) based on relative dimension changes.\r\n+        *   Handles save fallback: If primary 16-bit format (e.g., EXR) fails, attempts fallback (e.g., PNG).\r\n+    *   **Merging (`_merge_maps`):**\r\n+        *   Identifies common resolutions among required input maps for a given rule.\r\n+        *   Loads required processed input maps for each common resolution.\r\n+        *   Converts inputs to float32 (normalized 0-1).\r\n+        *   Injects default values (from rule `defaults`) for missing channels.\r\n+        *   Merges channels using `cv2.merge`.\r\n+        *   Determines output bit depth based on rule (`force_16bit`, `respect_inputs`).\r\n+        *   Determines output format similarly to map processing, considering the highest format among inputs if not forced lossless or over JPG threshold. Handles JPG 16-bit conflict by forcing 8-bit.\r\n+        *   Converts merged image to final target dtype.\r\n+        *   Handles save fallback (e.g., EXR->PNG).\r\n+    *   **Metadata (`_determine_base_metadata`, `_determine_single_asset_metadata`, `_generate_metadata_file`):**\r\n+        *   Base name determined using `source_naming` separator/index from `Configuration`, with fallback to common prefix or input name. Handles multiple assets within one input.\r\n+        *   Category determined by model presence or `decal_keywords` from `Configuration`.\r\n+        *   Archetype determined by matching keywords in `archetype_rules` (from `Configuration`) against file stems/base name.\r\n+        *   Final `metadata.json` populated by accumulating results (map details, stats, features, etc.) during the per-asset processing loop.\r\n+\r\n+*   **Blender Integration (`main.py:run_blender_script`, `gui/processing_handler.py:_run_blender_script_subprocess`):**\r\n+    *   Uses `subprocess.run` to execute Blender.\r\n+    *   Command includes `-b` (background), the target `.blend` file, `--python` followed by the script path (`blenderscripts/*.py`), and `--` separator.\r\n+    *   Arguments after `--` (currently just the `asset_root_dir`, and optionally the nodegroup blend path for the materials script) are passed to the Python script via `sys.argv`.\r\n+    *   Uses `--factory-startup` in GUI handler. Checks return code and logs stdout/stderr.\r\n+\r\n+--------------------------------\r\n+8. State Management\r\n+--------------------------------\r\n+\r\n+*   **`Configuration` Object:** Holds the loaded and merged configuration state (core + preset) and compiled regex patterns. Designed to be immutable after initialization. Instantiated once per worker process.\r\n+*   **`AssetProcessor` Instance:** Primarily stateless between calls to `process()`. State *within* a `process()` call is managed through local variables scoped to the overall call or the per-asset loop (e.g., `current_asset_metadata`, `processed_maps_details_asset`). `self.classified_files` is populated once by `_inventory_and_classify_files` early in `process()` and then used read-only (filtered copies) within the per-asset loop.\r\n+*   **`main.py` (CLI):** Tracks overall run progress (processed, skipped, failed counts) based on results returned from worker processes.\r\n+*   **`gui/processing_handler.py`:** Manages the state of a GUI processing run using internal flags (`_is_running`, `_cancel_requested`) and stores `Future` objects in `self._futures` dictionary while the pool is active.\r\n+\r\n+--------------------------------\r\n+9. Error Handling & Propagation\r\n+--------------------------------\r\n+\r\n+*   **Custom Exceptions:** `ConfigurationError` (raised by `Configuration` on load/validation failure), `AssetProcessingError` (raised by `AssetProcessor` for various processing failures).\r\n+*   **Configuration:** `ConfigurationError` halts initialization. Regex compilation errors are logged as warnings but do not stop initialization.\r\n+*   **AssetProcessor:** Uses `try...except Exception` within key pipeline steps (`_process_maps`, `_merge_maps`, etc.) and within the per-asset loop in `process()`. Errors specific to one asset are logged (`log.error(exc_info=True)`), the asset is marked \"failed\" in the returned status dictionary, and the loop continues to the next asset. Critical setup errors (e.g., workspace creation) raise `AssetProcessingError`, halting the entire `process()` call. Includes specific save fallback logic (EXR->PNG) on `cv2.imwrite` failure for 16-bit formats.\r\n+*   **Worker Wrapper (`main.py:process_single_asset_wrapper`):** Catches `ConfigurationError`, `AssetProcessingError`, and general `Exception` during worker execution. Logs the error and returns a (\"failed\", error_message) status tuple to the main process.\r\n+*   **Process Pool (`main.py`, `gui/processing_handler.py`):** The `with ProcessPoolExecutor(...)` block handles pool setup/teardown. A `try...except` around `as_completed` or `future.result()` catches critical worker failures (e.g., process crash).\r\n+*   **GUI Communication (`ProcessingHandler`):** Catches exceptions during `future.result()` retrieval. Emits `file_status_updated` signal with \"failed\" status and error message. Emits `processing_finished` with final counts.\r\n+*   **Blender Scripts:** Checks `subprocess.run` return code. Logs stderr as ERROR if return code is non-zero, otherwise as WARNING. Catches `FileNotFoundError` if the Blender executable path is invalid.\r\n+\r\n+--------------------------------\r\n+10. Key Data Structures\r\n+--------------------------------\r\n+\r\n+*   **`Configuration` Instance Attributes:**\r\n+    *   `compiled_map_keyword_regex`: `dict[str, list[tuple[re.Pattern, str, int]]]` (Base type -> list of compiled regex tuples)\r\n+    *   `compiled_extra_regex`, `compiled_model_regex`: `list[re.Pattern]`\r\n+    *   `compiled_bit_depth_regex_map`: `dict[str, re.Pattern]` (Base type -> compiled regex)\r\n+*   **`AssetProcessor` Internal Structures (within `process()`):**\r\n+    *   `self.classified_files`: `dict[str, list[dict]]` (Category -> list of file info dicts like `{'source_path': Path, 'map_type': str, ...}`)\r\n+    *   `processed_maps_details_asset`, `merged_maps_details_asset`: `dict[str, dict[str, dict]]` (Map Type -> Resolution Key -> Details Dict `{'path': Path, 'width': int, ...}`)\r\n+    *   `file_to_base_name_map`: `dict[Path, Optional[str]]` (Source relative path -> Determined asset base name or None)\r\n+    *   `current_asset_metadata`: `dict` (Accumulates name, category, archetype, stats, map details per asset)\r\n+*   **Return Values:**\r\n+    *   `AssetProcessor.process()`: `Dict[str, List[str]]` (e.g., `{\"processed\": [...], \"skipped\": [...], \"failed\": [...]}`)\r\n+    *   `main.process_single_asset_wrapper()`: `Tuple[str, str, Optional[str]]` (input_path, status_string, error_message)\r\n+*   **`ProcessingHandler._futures`:** `dict[Future, str]` (Maps `concurrent.futures.Future` object to the input path string)\r\n+*   **Image Data:** `numpy.ndarray` (Handled by OpenCV).\r\n+\r\n+--------------------------------\r\n+11. Concurrency Models (CLI & GUI)\r\n+--------------------------------\r\n+\r\n+*   **Common Core:** Both CLI and GUI utilize `concurrent.futures.ProcessPoolExecutor` for parallel processing. The target function executed by workers is `main.process_single_asset_wrapper`.\r\n+*   **Isolation:** Crucially, `Configuration` and `AssetProcessor` objects are instantiated *within* the `process_single_asset_wrapper` function, meaning each worker process gets its own independent configuration and processor instance based on the arguments passed. This prevents state conflicts between concurrent asset processing tasks. Data is passed between the main process and workers via pickling of arguments and return values.\r\n+*   **CLI Orchestration (`main.py:run_processing`):**\r\n+    *   Creates the `ProcessPoolExecutor`.\r\n+    *   Submits all `process_single_asset_wrapper` tasks.\r\n+    *   Uses `concurrent.futures.as_completed` to iterate over finished futures as they complete, blocking until the next one is done.\r\n+    *   Gathers results synchronously within the main script's execution flow.\r\n+*   **GUI Orchestration (`gui/processing_handler.py`):**\r\n+    *   The `ProcessingHandler` object (a `QObject`) contains the `run_processing` method.\r\n+    *   This method is intended to be run in a separate `QThread` (managed by `MainWindow`) to avoid blocking the main UI thread.\r\n+    *   Inside `run_processing`, it creates and manages the `ProcessPoolExecutor`.\r\n+    *   It uses `as_completed` similarly to the CLI to iterate over finished futures.\r\n+    *   **Communication:** Instead of blocking the thread gathering results, it emits Qt signals (`progress_updated`, `file_status_updated`, `processing_finished`) from within the `as_completed` loop. These signals are connected to slots in `MainWindow` (running on the main UI thread), allowing for thread-safe updates to the GUI (progress bar, table status, status bar messages).\r\n+*   **Cancellation (GUI - `gui/processing_handler.py:request_cancel`):**\r\n+    *   Sets an internal `_cancel_requested` flag.\r\n+    *   Attempts `executor.shutdown(wait=False)` which prevents new tasks from starting and may cancel pending ones (depending on Python version).\r\n+    *   Manually iterates through stored `_futures` and calls `future.cancel()` on those not yet running or done.\r\n+    *   **Limitation:** This does *not* forcefully terminate worker processes that are already executing the `process_single_asset_wrapper` function. Cancellation primarily affects pending tasks and the processing of results from already running tasks (they will be marked as failed/cancelled when their future completes).\r\n+\r\n+--------------------------------\r\n+12. Resource Management\r\n+--------------------------------\r\n+\r\n+*   **Configuration:** Preset JSON files are opened and closed using `with open(...)`.\r\n+*   **AssetProcessor:**\r\n+    *   Temporary workspace directory created using `tempfile.mkdtemp()`.\r\n+    *   Cleanup (`_cleanup_workspace`) uses `shutil.rmtree()` and is called within a `finally` block in the main `process()` method, ensuring cleanup attempt even if errors occur.\r\n+    *   Metadata JSON file written using `with open(...)`.\r\n+    *   Image data is loaded into memory using OpenCV/NumPy; memory usage depends on image size and number of concurrent workers.\r\n+*   **Process Pool:** The `ProcessPoolExecutor` manages the lifecycle of worker processes. Using it within a `with` statement (as done in `main.py` and `gui/processing_handler.py`) ensures proper shutdown and resource release for the pool itself.\r\n+\r\n+--------------------------------\r\n+13. Known Limitations & Edge Cases\r\n+--------------------------------\r\n+\r\n+*   **Configuration:**\r\n+    *   Validation (`_validate_configs`) is primarily structural (key presence, basic types), not deeply logical (e.g., doesn't check if regex patterns are *sensible*).\r\n+    *   Regex compilation errors in `_compile_regex_patterns` are logged as warnings but don't prevent `Configuration` initialization, potentially leading to unexpected classification later.\r\n+    *   `_fnmatch_to_regex` helper only handles basic `*` and `?` wildcards. Complex fnmatch patterns might not translate correctly.\r\n+*   **AssetProcessor:**\r\n+    *   Heavily reliant on correct filename patterns and rules defined in presets. Ambiguous or incorrect patterns lead to misclassification.\r\n+    *   Potential for high memory usage when processing very large images, especially with many workers.\r\n+    *   Error handling within `process()` is per-asset; a failure during map processing for one asset marks the whole asset as failed, without attempting other maps for that asset. No partial recovery within an asset.\r\n+    *   Gloss->Roughness inversion assumes gloss map is single channel or convertible to grayscale.\r\n+    *   `predict_output_structure` and `get_detailed_file_predictions` use simplified logic (e.g., assuming PNG output, highest resolution only) and may not perfectly match final output names/formats in all cases.\r\n+    *   Filename sanitization (`_sanitize_filename`) is basic and might not cover all edge cases for all filesystems.\r\n+*   **CLI (`main.py`):**\r\n+    *   Preset existence check (`{preset}.json`) happens only in the main process before workers start.\r\n+    *   Blender executable finding logic relies on `config.py` path being valid or `blender` being in the system PATH.\r\n+*   **GUI Concurrency (`gui/processing_handler.py`):**\r\n+    *   Cancellation (`request_cancel`) is not immediate for tasks already running in worker processes. It prevents new tasks and stops processing results from completed futures once the flag is checked.\r\n+*   **General:**\r\n+    *   Limited input format support (ZIP archives, folders). Internal file formats limited by OpenCV (`cv2.imread`, `cv2.imwrite`). Optional `OpenEXR` package recommended for full EXR support.\r\n+    *   Error messages propagated from workers might lack full context in some edge cases.\n\\ No newline at end of file\n"
                },
                {
                    "date": 1745339118689,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -136,15 +136,16 @@\n         *   Multi-pass approach: Explicit Extra (regex) -> Models (regex) -> Potential Maps (keyword regex) -> Standalone 16-bit check (regex) -> Prioritize 16-bit variants -> Final Maps -> Remaining as Unrecognised (Extra).\r\n         *   Uses compiled regex patterns provided by the `Configuration` object passed during initialization.\r\n         *   Sorts potential map variants based on: 1. Preset rule index, 2. Keyword index within rule, 3. Alphabetical path. Suffixes (`-1`, `-2`) are assigned later per-asset based on this sort order and `RESPECT_VARIANT_MAP_TYPES`.\r\n     *   **Map Processing (`_process_maps`):**\r\n-        *   Loads images using `cv2.imread` (flags: `IMREAD_UNCHANGED` or `IMREAD_GRAYSCALE`). Converts BGR to RGB if needed.\r\n+        *   Loads images using `cv2.imread` (flags: `IMREAD_UNCHANGED` or `IMREAD_GRAYSCALE`). Converts loaded 3-channel images from BGR to RGB for internal consistency (stats, merging).\r\n+        *   **Saving Channel Order:** Before saving with `cv2.imwrite`, 3-channel images are conditionally converted back from RGB to BGR *only* if the target output format is *not* EXR (e.g., for PNG, JPG, TIF). This ensures correct channel order for standard formats while preserving RGB for EXR. (Fix for ISSUE-010).\r\n         *   Handles Gloss->Roughness inversion: Loads gloss, inverts using float math (`1.0 - img/norm`), stores as float32 with original dtype. Prioritizes gloss source if both gloss and native rough exist.\r\n         *   Resizes using `cv2.resize` (interpolation: `INTER_LANCZOS4` for downscale, `INTER_CUBIC` for potential same-size/upscale - though upscaling is generally avoided by checks).\r\n         *   Determines output format based on hierarchy: `FORCE_LOSSLESS_MAP_TYPES` > `RESOLUTION_THRESHOLD_FOR_JPG` > Input format priority (TIF/EXR often lead to lossless) > Configured defaults (`OUTPUT_FORMAT_16BIT_PRIMARY`, `OUTPUT_FORMAT_8BIT`).\r\n         *   Determines output bit depth based on `MAP_BIT_DEPTH_RULES` ('respect' vs 'force_8bit').\r\n         *   Converts dtype before saving (e.g., float to uint8/uint16 using scaling factors 255.0/65535.0).\r\n-        *   Calculates stats (`_calculate_image_stats`) on normalized float64 data for a specific resolution (`CALCULATE_STATS_RESOLUTION`).\r\n+        *   Calculates stats (`_calculate_image_stats`) on normalized float64 data (in RGB space) for a specific resolution (`CALCULATE_STATS_RESOLUTION`).\r\n         *   Calculates aspect ratio string (`_normalize_aspect_ratio_change`) based on relative dimension changes.\r\n         *   Handles save fallback: If primary 16-bit format (e.g., EXR) fails, attempts fallback (e.g., PNG).\r\n     *   **Merging (`_merge_maps`):**\r\n         *   Identifies common resolutions among required input maps for a given rule.\r\n"
                },
                {
                    "date": 1745344848180,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -146,18 +146,18 @@\n         *   Converts dtype before saving (e.g., float to uint8/uint16 using scaling factors 255.0/65535.0).\r\n         *   Calculates stats (`_calculate_image_stats`) on normalized float64 data (in RGB space) for a specific resolution (`CALCULATE_STATS_RESOLUTION`).\r\n         *   Calculates aspect ratio string (`_normalize_aspect_ratio_change`) based on relative dimension changes.\r\n         *   Handles save fallback: If primary 16-bit format (e.g., EXR) fails, attempts fallback (e.g., PNG).\r\n-    *   **Merging (`_merge_maps`):**\r\n-        *   Identifies common resolutions among required input maps for a given rule.\r\n-        *   Loads required processed input maps for each common resolution.\r\n-        *   Converts inputs to float32 (normalized 0-1).\r\n+    *   **Merging (`_merge_maps_from_source`):**\r\n+        *   Identifies the required *source* files for merge inputs based on classified files.\r\n+        *   Determines common resolutions based on available processed maps (as a proxy for size compatibility).\r\n+        *   Loads required source maps for each common resolution using the `_load_and_transform_source` helper (utilizing the cache).\r\n+        *   Converts loaded inputs to float32 (normalized 0-1).\r\n         *   Injects default values (from rule `defaults`) for missing channels.\r\n         *   Merges channels using `cv2.merge`.\r\n         *   Determines output bit depth based on rule (`force_16bit`, `respect_inputs`).\r\n-        *   Determines output format similarly to map processing, considering the highest format among inputs if not forced lossless or over JPG threshold. Handles JPG 16-bit conflict by forcing 8-bit.\r\n-        *   Converts merged image to final target dtype.\r\n-        *   Handles save fallback (e.g., EXR->PNG).\r\n+        *   Determines output format based on complex rules (`config.py` and preset), considering the highest format among *source* inputs if not forced lossless or over JPG threshold. Handles JPG 16-bit conflict by forcing 8-bit.\r\n+        *   Saves the merged image using the `_save_image` helper, including final data type/color space conversions and fallback logic (e.g., EXR->PNG).\r\n     *   **Metadata (`_determine_base_metadata`, `_determine_single_asset_metadata`, `_generate_metadata_file`):**\r\n         *   Base name determined using `source_naming` separator/index from `Configuration`, with fallback to common prefix or input name. Handles multiple assets within one input.\r\n         *   Category determined by model presence or `decal_keywords` from `Configuration`.\r\n         *   Archetype determined by matching keywords in `archetype_rules` (from `Configuration`) against file stems/base name.\r\n"
                }
            ],
            "date": 1745327520295,
            "name": "Commit-0",
            "content": "================================\r\nAsset Processor Tool - Developer Documentation\r\n================================\r\n\r\nThis document provides a concise overview of the Asset Processor Tool's codebase for developers joining the project. It focuses on the architecture, key components, and development workflow.\r\n\r\n**NOTE:** This documentation strictly excludes details on environment setup, dependency installation, building the project, or deployment procedures. It assumes familiarity with Python and the relevant libraries (OpenCV, NumPy, PySide6).\r\n\r\n--------------------------------\r\n1. Project Overview\r\n--------------------------------\r\n\r\n*   **Purpose:** To process 3D asset source files (texture sets, models, etc., typically from ZIP archives or folders) into a standardized library format.\r\n*   **Core Functionality:** Uses configurable JSON presets to interpret different asset sources, automating tasks like file classification, image resizing, channel merging, and metadata generation.\r\n*   **High-Level Architecture:** Consists of a core processing engine (`AssetProcessor`), a configuration system handling presets (`Configuration`), multiple interfaces (GUI, CLI, Directory Monitor), and optional integration with Blender for automated material/nodegroup creation.\r\n\r\n--------------------------------\r\n2. Codebase Structure\r\n--------------------------------\r\n\r\nKey files and directories:\r\n\r\n*   `asset_processor.py`: Contains the `AssetProcessor` class, the core logic for processing a single asset through the pipeline. Includes methods for classification, map processing, merging, metadata generation, and output organization. Also provides methods for predicting output structure used by the GUI.\r\n*   `configuration.py`: Defines the `Configuration` class. Responsible for loading core settings from `config.py` and merging them with a specified preset JSON file (`Presets/*.json`). Pre-compiles regex patterns from presets for efficiency.\r\n*   `config.py`: Stores global default settings, constants, and core rules (e.g., standard map types, default resolutions, merge rules, output format rules, Blender paths).\r\n*   `main.py`: Entry point for the Command-Line Interface (CLI). Handles argument parsing, logging setup, parallel processing orchestration (using `concurrent.futures.ProcessPoolExecutor`), calls `AssetProcessor` via a wrapper function, and optionally triggers Blender scripts.\r\n*   `monitor.py`: Implements the automated directory monitoring feature using the `watchdog` library. Contains the `ZipHandler` class to detect new ZIP files and trigger processing via `main.run_processing`.\r\n*   `gui/`: Directory containing all code related to the Graphical User Interface (GUI), built with PySide6.\r\n    *   `main_window.py`: Defines the `MainWindow` class, the main application window structure, UI layout (preset editor, processing panel, drag-and-drop, preview table, controls), event handling (button clicks, drag/drop), and menu setup. Manages GUI-specific logging (`QtLogHandler`).\r\n    *   `processing_handler.py`: Defines the `ProcessingHandler` class (runs on a `QThread`). Manages the execution of the main asset processing pipeline (using `ProcessPoolExecutor`) and Blender script execution in the background to keep the GUI responsive. Communicates progress and results back to the `MainWindow` via signals.\r\n    *   `prediction_handler.py`: Defines the `PredictionHandler` class (runs on a `QThread`). Manages background file analysis/preview generation by calling `AssetProcessor.get_detailed_file_predictions()`. Sends results back to the `MainWindow` via signals to update the preview table.\r\n    *   `preview_table_model.py`: Defines `PreviewTableModel` (inherits `QAbstractTableModel`) and `PreviewSortFilterProxyModel` for managing and displaying data in the GUI's preview table, including custom sorting logic.\r\n*   `blenderscripts/`: Contains Python scripts (`create_nodegroups.py`, `create_materials.py`) designed to be executed *within* Blender, typically triggered by the main tool after processing to automate PBR nodegroup and material setup in `.blend` files.\r\n*   `Presets/`: Contains supplier-specific configuration files in JSON format (e.g., `Poliigon.json`). These define rules for interpreting asset filenames, classifying maps, handling variants, etc. `_template.json` serves as a base for new presets.\r\n*   `Testfiles/`: Contains example input assets for testing purposes.\r\n*   `Tickets/`: Directory for issue and feature tracking using Markdown files.\r\n\r\n--------------------------------\r\n3. Key Components/Modules\r\n--------------------------------\r\n\r\n*   **`AssetProcessor` (`asset_processor.py`):** The heart of the tool. Orchestrates the entire processing pipeline for a single input asset (ZIP or folder). Responsibilities include workspace management, file classification, metadata extraction, map processing (resizing, format conversion), channel merging, `metadata.json` generation, and organizing final output files.\r\n*   **`Configuration` (`configuration.py`):** Manages the loading and merging of configuration settings. Takes a preset name, loads defaults from `config.py`, loads the specified `Presets/*.json`, merges them, validates settings, and pre-compiles regex patterns defined in the preset for efficient use by `AssetProcessor`.\r\n*   **`MainWindow` (`gui/main_window.py`):** The main class for the GUI application. Sets up the UI layout, connects user actions (button clicks, drag/drop) to slots, manages the preset editor, interacts with background handlers (`ProcessingHandler`, `PredictionHandler`) via signals/slots, and displays feedback (logs, progress, status).\r\n*   **`ProcessingHandler` (`gui/processing_handler.py`):** Handles the execution of the core asset processing logic and Blender scripts in a background thread for the GUI. Manages the `ProcessPoolExecutor` for parallel asset processing and communicates progress/results back to the `MainWindow`.\r\n*   **`PredictionHandler` (`gui/prediction_handler.py`):** Handles the generation of file classification previews in a background thread for the GUI. Calls `AssetProcessor`'s prediction methods and sends results back to the `MainWindow` to populate the preview table without blocking the UI.\r\n*   **`ZipHandler` (`monitor.py`):** A `watchdog` event handler used by `monitor.py`. Detects newly created ZIP files in the monitored input directory, validates the filename format (for preset extraction), and triggers the main processing logic via `main.run_processing`.\r\n\r\n--------------------------------\r\n4. Core Concepts & Data Flow\r\n--------------------------------\r\n\r\n*   **Preset-Driven Configuration:**\r\n    *   Global defaults are set in `config.py`.\r\n    *   Supplier-specific rules (filename patterns, map keywords, variant handling, etc.) are defined using regex in `Presets/*.json` files.\r\n    *   The `Configuration` class loads `config.py` and merges it with the selected preset JSON, providing a unified configuration object to the `AssetProcessor`. Regex patterns are pre-compiled during `Configuration` initialization for performance.\r\n\r\n*   **Asset Processing Pipeline (Simplified Flow):**\r\n    1.  **Workspace Setup:** Create a temporary directory.\r\n    2.  **Extract/Copy:** Extract ZIP or copy folder contents to the workspace.\r\n    3.  **Classify Files:** Scan workspace, use compiled regex from `Configuration` to classify files (Map, Model, Extra, Ignored, Unrecognized). Handle 16-bit variants and assign suffixes based on rules.\r\n    4.  **Determine Metadata:** Extract asset name, category, archetype based on preset rules.\r\n    5.  **Skip Check:** If overwrite is false, check if output already exists; if so, skip this asset.\r\n    6.  **Process Maps:** Load images, resize (no upscale), convert format/bit depth based on complex rules (`config.py` and preset), handle Gloss->Roughness inversion, calculate stats, determine aspect ratio change. Save processed maps.\r\n    7.  **Merge Maps:** Combine channels from different processed maps based on `MAP_MERGE_RULES` in `config.py`. Save merged maps.\r\n    8.  **Generate `metadata.json`:** Collect all relevant information (map details, stats, aspect ratio, category, etc.) and write to `metadata.json` in the workspace.\r\n    9.  **Organize Output:** Create the final output directory structure (`<output_base>/<supplier>/<asset_name>/`) and move processed maps, merged maps, models, `metadata.json`, Extra files, and Ignored files into it.\r\n    10. **Cleanup Workspace:** Delete the temporary directory.\r\n    11. **(Optional) Blender Scripts:** If triggered via CLI/GUI, execute `blenderscripts/*.py` using the configured Blender executable via a subprocess.\r\n\r\n*   **Parallel Processing:**\r\n    *   Multiple input assets are processed concurrently using `concurrent.futures.ProcessPoolExecutor`.\r\n    *   This pool is managed by `main.py` (CLI) or `gui/processing_handler.py` (GUI).\r\n    *   Each asset runs in an isolated worker process, ensuring separate `Configuration` and `AssetProcessor` instances.\r\n\r\n*   **GUI Interaction & Threading:**\r\n    *   The GUI (`PySide6`) uses `QThread` to run `ProcessingHandler` (asset processing) and `PredictionHandler` (file preview generation) in the background, preventing the UI from freezing.\r\n    *   Communication between the main UI thread (`MainWindow`) and background threads relies on Qt's signals and slots mechanism for thread safety (e.g., updating progress, status messages, preview table data).\r\n    *   `PredictionHandler` calls `AssetProcessor` methods to get file classification details, which are then sent back to `MainWindow` to populate the `PreviewTableModel`.\r\n\r\n*   **Output (`metadata.json`):**\r\n    *   A key output file generated for each processed asset.\r\n    *   Contains structured data about the asset: map filenames, resolutions, formats, bit depths, merged map details, calculated image statistics, aspect ratio change info, asset category/archetype, source preset used, list of ignored source files, etc. This file is intended for use by downstream tools or scripts (like the Blender integration scripts).\r\n\r\n--------------------------------\r\n5. Development Workflow\r\n--------------------------------\r\n\r\n*   **Modifying Core Processing Logic:** Changes to how assets are classified, maps are processed/resized/converted, channels are merged, or metadata is generated typically involve editing the `AssetProcessor` class in `asset_processor.py`.\r\n*   **Changing Global Settings/Rules:** Adjustments to default output paths, standard resolutions, default format rules, map merge definitions, or Blender paths should be made in `config.py`.\r\n*   **Adding/Modifying Supplier Rules:** To add support for a new asset source or change how an existing one is interpreted, create or edit the corresponding JSON file in the `Presets/` directory. Refer to `_template.json` and existing presets for structure. Focus on defining accurate regex patterns in `map_type_mapping`, `bit_depth_variants`, `model_patterns`, `source_naming_convention`, etc.\r\n*   **Adjusting CLI Behavior:** Changes to command-line arguments, argument parsing, or the overall CLI workflow are handled in `main.py`.\r\n*   **Modifying the GUI:** UI layout changes, adding new controls, altering event handling, or modifying background task management for the GUI involves working within the `gui/` directory, primarily `main_window.py`, `processing_handler.py`, and `prediction_handler.py`. UI elements are built using PySide6 widgets.\r\n*   **Enhancing Blender Integration:** Improvements or changes to how nodegroups or materials are created in Blender require editing the Python scripts within the `blenderscripts/` directory. Consider how these scripts are invoked and what data they expect (primarily from `metadata.json` and command-line arguments passed via subprocess calls in `main.py` or `gui/processing_handler.py`).\r\n\r\n--------------------------------\r\n6. Coding Conventions\r\n--------------------------------\r\n\r\n*   **Object-Oriented:** The codebase heavily utilizes classes (e.g., `AssetProcessor`, `Configuration`, `MainWindow`, various Handlers).\r\n*   **Type Hinting:** Python type hints are used throughout the code for clarity and static analysis.\r\n*   **Logging:** Standard Python `logging` module is used for logging messages at different levels (DEBUG, INFO, WARNING, ERROR). The GUI uses a custom `QtLogHandler` to display logs in the UI console.\r\n*   **Error Handling:** Uses standard `try...except` blocks and defines some custom exceptions (e.g., `ConfigurationError`, `AssetProcessingError`).\r\n*   **Parallelism:** Uses `concurrent.futures.ProcessPoolExecutor` for CPU-bound tasks (asset processing).\r\n*   **GUI:** Uses `PySide6` (Qt for Python) with signals and slots for communication between UI elements and background threads (`QThread`).\r\n*   **Configuration:** Relies on Python modules (`config.py`) for core settings and JSON files (`Presets/`) for specific rule sets.\r\n*   **File Paths:** Uses `pathlib.Path` for handling file system paths."
        }
    ]
}