Asset-Frameworker/Documentation/02_Developer_Guide/03_Key_Components.md

Developer Guide: Key Components

This document describes the major classes and modules that form the core of the Asset Processor Tool.

AssetProcessor (asset_processor.py)

The AssetProcessor class is the central engine of the tool. It is responsible for processing a single input asset (either a ZIP archive or a folder) through the entire pipeline. Its key responsibilities include:

• Setting up and cleaning up a temporary workspace for processing.
• Extracting or copying input files to the workspace.
• Inventorying and classifying files based on configured rules (maps, models, extra, ignored, unrecognised).
• Determining asset metadata such as name, category, and archetype.
• Processing texture maps (resizing, format/bit depth conversion, handling Gloss->Roughness inversion, calculating statistics).
• Merging channels from different maps according to merge rules.
• Generating the metadata.json file containing details about the processed asset.
• Organizing the final output files into the structured library directory.
• Accepting a SourceRule object which represents the hierarchical rules (Source, Asset, File) that can override static configuration values.
• Implementing the logic (_get_rule_with_fallback) to retrieve configuration values by prioritizing rules in the order: File -> Asset -> Source -> Static Config.
• Applying this hierarchical rule logic during file classification, prediction, image processing, and metadata generation.
• Providing methods (get_detailed_file_predictions) used by the GUI for previewing file classification, now incorporating the hierarchical rules.

Rule Structure (rule_structure.py)

This module defines the data structures used to represent the hierarchical processing rules:

• SourceRule: A dataclass representing rules applied at the source level. It contains nested AssetRule objects.
• AssetRule: A dataclass representing rules applied at the asset level. It contains nested FileRule objects.
• FileRule: A dataclass representing rules applied at the file level.

These classes hold specific rule parameters (e.g., supplier_identifier, asset_type, map_type_override) and support serialization (Pickle, JSON) to allow them to be passed between different parts of the application, including across process boundaries.

Rule Hierarchy Model (gui/rule_hierarchy_model.py)

The RuleHierarchyModel implements a QAbstractItemModel for use with Qt's model-view architecture. It is specifically designed to:

• Wrap a SourceRule object and expose its hierarchical structure (Source -> Asset -> File) to a QTreeView.
• Provide methods (data, index, parent, rowCount, columnCount) required by QAbstractItemModel to allow the QTreeView to display the rule hierarchy.
• Enable navigation and selection within the rule hierarchy in the GUI.

Rule Editor Widget (gui/rule_editor_widget.py)

The RuleEditorWidget is a custom Qt widget that provides a user interface for viewing and editing the attributes of a selected rule object (SourceRule, AssetRule, or FileRule). It dynamically generates input fields (e.g., line edits, checkboxes) based on the attributes of the rule object it is currently displaying. It allows users to modify the dynamic rule parameters through the GUI.

Configuration (configuration.py)

The Configuration class manages the tool's settings. It is responsible for:

• Loading the core default settings defined in config.py.
• Loading the supplier-specific rules from a selected preset JSON file (Presets/*.json).
• Merging the core settings and preset rules into a single, unified configuration object.
• Validating the loaded configuration to ensure required settings are present.
• Pre-compiling regular expression patterns defined in the preset for efficient file classification by the AssetProcessor.

An instance of the Configuration class is typically created once per asset processing task (within a worker process) to ensure isolated and correct settings for each asset.

MainWindow (gui/main_window.py)

The MainWindow class is the main application window for the Graphical User Interface (GUI). It handles the overall UI layout and user interaction:

• Sets up the main window structure, including panels for the preset editor and processing controls.
• Manages the layout of UI elements like the drag-and-drop area, preview table, buttons, and status bar.
• Connects user actions (button clicks, drag/drop events) to corresponding handler methods (slots).
• Interacts with background processing and prediction handlers (ProcessingHandler, PredictionHandler) via Qt signals and slots to update the UI safely from background threads.
• Manages the GUI-specific logging handler (QtLogHandler) to display logs in the UI console.

ProcessingHandler (gui/processing_handler.py)

The ProcessingHandler class is designed to run in a separate QThread within the GUI. Its purpose is to manage the execution of the main asset processing pipeline and optional Blender scripts in the background, preventing the GUI from freezing. It:

• Manages a concurrent.futures.ProcessPoolExecutor to run individual asset processing tasks (AssetProcessor.process()) in separate worker processes.
• Submits processing tasks to the pool and monitors their completion.
• Communicates progress, status updates, and results back to the MainWindow using Qt signals.
• Handles the execution of Blender scripts via subprocess calls after asset processing is complete.
• Provides logic for cancelling ongoing processing tasks (though cancellation of already running worker processes is not immediate).

PredictionHandler (gui/prediction_handler.py)

The PredictionHandler class also runs in a separate QThread in the GUI. It is responsible for generating file classification previews in the background without blocking the UI. It:

• Calls methods on the AssetProcessor (specifically get_detailed_file_predictions) to analyze input files and predict their classification and output names based on the selected processing preset.
• Uses a ThreadPoolExecutor for potentially concurrent prediction tasks.
• Sends the prediction results back to the MainWindow via Qt signals to update the preview table.

ZipHandler (monitor.py)

The ZipHandler is a custom event handler used by the monitor.py script, built upon the watchdog library. It is responsible for:

• Detecting file system events, specifically the creation of new .zip files, in the monitored input directory.
• Validating the filename format of detected ZIPs to extract the intended preset name.
• Triggering the main asset processing logic (main.run_processing) for valid new ZIP files.
• Managing the movement of processed source ZIP files to 'processed' or 'error' directories.

These key components work together to provide the tool's functionality, separating concerns and utilizing concurrency for performance and responsiveness.

Note on Data Passing: As mentioned in the Architecture documentation, major changes to the data passing mechanisms between the GUI, Main (CLI orchestration), and AssetProcessor modules are currently being planned. The descriptions of module interactions and data flow within this document reflect the current state and will require review and updates once the plan for these changes is finalized.