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.

ProcessingEngine (processing_engine.py)

The ProcessingEngine class is the new core component responsible for executing the asset processing pipeline for a single input asset. Unlike the older AssetProcessor, this engine operates solely based on a complete SourceRule object provided to its process() method and the static Configuration object passed during initialization. It contains no internal prediction, classification, or fallback logic. Its key responsibilities include:

• Setting up and cleaning up a temporary workspace for processing.
• Extracting or copying input files to the workspace.
• Processing files based on the explicit rules and predicted values contained within the input SourceRule.
• Processing texture maps (resizing, format/bit depth conversion, inversion, stats calculation) using parameters from the SourceRule or static Configuration.
• Merging channels based on rules defined in the static Configuration and parameters from the SourceRule.
• Generating the metadata.json file containing details about the processed asset, incorporating information from the SourceRule.
• Organizing the final output files into the structured library directory.

AssetProcessor (asset_processor.py)

The AssetProcessor class is the older processing engine. It is kept in the codebase for reference but is no longer used in the main processing flow orchestrated by main.py or the GUI. Its original role was similar to the new ProcessingEngine, but it included internal prediction, classification, and fallback logic based on hierarchical rules and static configuration.

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, asset_type_override, item_type, item_type_override, target_asset_name_override). Attributes like asset_type and item_type_override now use string types, which are validated against centralized lists in config.py. These structures support serialization (Pickle, JSON) to allow them to be passed between different parts of the application, including across process boundaries.

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 PredictionHandler.

An instance of the Configuration class is typically created once per application run (or per processing batch) and passed to the ProcessingEngine.

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:

• Defines the main application window structure and layout using PySide6 widgets.
• Arranges the Preset Editor panel (left) and the Unified Hierarchical View (right).
• Setting up the menu bar, including the "View" menu for toggling the Log Console.
• Connecting user interactions (button clicks, drag-and-drop events, edits in the Unified View) to corresponding methods (slots) within the MainWindow or other handler classes.
• Managing the display of application logs in the UI console using a custom QtLogHandler.
• Interacting with background handlers (ProcessingHandler, PredictionHandler) via Qt signals and slots to ensure thread-safe updates to the UI during long-running operations.
• Receiving the initial SourceRule hierarchy from the PredictionHandler and populating the UnifiedViewModel.
• Sending the final, potentially user-modified, SourceRule list to main.py to initiate processing via the ProcessingEngine.

Unified View Model (gui/unified_view_model.py)

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

• Wrap a list of SourceRule objects and expose their hierarchical structure (Source -> Asset -> File) to a QTreeView (the Unified Hierarchical View).
• Provide methods (data, index, parent, rowCount, columnCount, flags, setData) required by QAbstractItemModel to allow the QTreeView to display the rule hierarchy and support inline editing of specific attributes (e.g., supplier_override, asset_type_override, item_type_override, target_asset_name_override).
• Handle the direct restructuring of the underlying SourceRule hierarchy when target_asset_name_override is edited, including moving FileRules and managing AssetRule creation/deletion.
• Determine row background colors based on the asset_type and item_type/item_type_override using color metadata from config.py.
• Hold the SourceRule data that is the single source of truth for the GUI's processing rules.

Delegates (gui/delegates.py)

This module contains custom QStyledItemDelegate implementations used by the Unified Hierarchical View (QTreeView) to provide inline editors for specific data types or rule attributes. Examples include delegates for:

• ComboBoxDelegate: For selecting from predefined lists of allowed asset and file types, sourced from config.py.
• LineEditDelegate: For free-form text editing, such as the target_asset_name_override.
• SupplierSearchDelegate: A new delegate for the "Supplier" column. It provides a QLineEdit with auto-completion suggestions loaded from config/suppliers.json and handles adding/saving new suppliers.

These delegates handle the presentation and editing of data within the tree view cells, interacting with the UnifiedViewModel to get and set data.

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 using the ProcessingEngine in the background, preventing the GUI from freezing. It:

• Manages a concurrent.futures.ProcessPoolExecutor to run individual asset processing tasks (ProcessingEngine.process()) in separate worker processes.
• Submits processing tasks to the pool, passing the relevant SourceRule object and Configuration instance to the ProcessingEngine.
• Monitors task completion and communicates progress, status updates, and results back to the MainWindow using Qt signals.
• Handles the execution of optional Blender scripts via subprocess calls after asset processing is complete.
• Provides logic for cancelling ongoing processing tasks.

PredictionHandler (gui/prediction_handler.py)

The PredictionHandler class also runs in a separate QThread in the GUI. It is responsible for generating the initial SourceRule hierarchy with predicted values based on the input files and the selected preset. It:

• Takes an input source identifier (path), a list of files within that source, and the selected preset name as input.
• Uses logic (including accessing preset rules and config.py's allowed types) to analyze files and predict initial values for overridable fields in the SourceRule, AssetRule, and FileRule objects (e.g., supplier_identifier, asset_type, item_type, target_asset_name_override).
• Constructs a SourceRule hierarchy for the single input source.
• Emits a signal (rule_hierarchy_ready) with the input source identifier and the generated SourceRule object (within a list) to the MainWindow for accumulation and eventual population of the UnifiedViewModel.

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. The SourceRule object serves as a clear data contract between the GUI/prediction layer and the processing engine.