Asset-Frameworker/ProjectNotes/Data_Structures/Preview_Edit_Interface.md

Data Interface: GUI Preview Edits to Processing Handler

1. Purpose

This document defines the data structures and interface used to pass user edits made in the GUI's file preview table (specifically changes to 'Status' and 'Predicted Asset' output name) to the backend ProcessingHandler. It also incorporates a structure for future asset-level properties.

2. Data Structures

Two primary data structures are used:

2.1. File Data (file_list)

• Type: list[dict]
• Description: A flat list where each dictionary represents a single file identified during the prediction phase. This list is modified by the GUI to reflect user edits to file status and output names.
• Dictionary Keys (per file):
  • original_path (str): The full path to the source file. (Read-only by GUI)
  • predicted_asset_name (str | None): The name of the asset group the file belongs to, derived from input. (Read-only by GUI)
  • predicted_output_name (str | None): The backend's predicted final output filename. EDITABLE by the user in the GUI ('Predicted Asset' column).
  • status (str): The backend's predicted status (e.g., 'Mapped', 'Ignored'). EDITABLE by the user in the GUI ('Status' column).
  • details (str | None): Additional information or error messages. (Read-only by GUI, potentially updated by model validation).
  • source_asset (str): An identifier for the source asset group (e.g., input folder/zip name). (Read-only by GUI)

2.2. Asset Properties (asset_properties)

• Type: dict[str, dict]
• Description: A dictionary mapping the source_asset identifier (string key) to a dictionary of asset-level properties determined by the backend prediction/preset. This structure is initially read-only in the GUI but designed for future expansion (e.g., editing asset category).
• Asset Properties Dictionary Keys (Example):
  • asset_category (str): The determined category (e.g., 'surface', 'model').
  • asset_tags (list[str]): Any relevant tags associated with the asset.
  • (Other future asset-level properties can be added here)

3. Data Flow & Interface

graph LR
    subgraph Backend
        A[Prediction Logic] -- Generates --> B(file_list);
        A -- Generates --> C(asset_properties);
    end

    subgraph GUI Components
        D[PredictionHandler] -- prediction_results_ready(file_list, asset_properties) --> E(PreviewTableModel);
        E -- Stores & Allows Edits --> F(Internal file_list);
        E -- Stores --> G(Internal asset_properties);
        H[MainWindow] -- Retrieves --> F;
        H -- Retrieves --> G;
        H -- Passes (file_list, asset_properties) --> I[ProcessingHandler];
    end

    subgraph Backend
        I -- Uses Edited --> F;
        I -- Uses Read-Only --> G;
    end

    style A fill:#lightblue,stroke:#333,stroke-width:1px
    style B fill:#lightgreen,stroke:#333,stroke-width:1px
    style C fill:#lightyellow,stroke:#333,stroke-width:1px
    style D fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#ccf,stroke:#333,stroke-width:2px
    style F fill:#lightgreen,stroke:#333,stroke-width:1px
    style G fill:#lightyellow,stroke:#333,stroke-width:1px
    style H fill:#f9f,stroke:#333,stroke-width:2px
    style I fill:#lightblue,stroke:#333,stroke-width:2px

1. Prediction: The PredictionHandler generates both the file_list and asset_properties.
2. Signal: It emits a signal (e.g., prediction_results_ready) containing both structures, likely as a tuple (file_list, asset_properties).
3. Table Model: The PreviewTableModel receives the tuple. It stores asset_properties (read-only for now). It stores file_list and allows user edits to the status and predicted_output_name values within this list.
4. Processing Trigger: When the user initiates processing, the MainWindow retrieves the (potentially modified) file_list and the (unmodified) asset_properties from the PreviewTableModel.
5. Processing Execution: The MainWindow passes both structures to the ProcessingHandler.
6. Handler Logic: The ProcessingHandler iterates through the file_list. For each file, it uses the potentially edited status and predicted_output_name. If asset-level information is needed, it uses the file's source_asset key to look up the data in the asset_properties dictionary.

4. Example Data Passed to ProcessingHandler

• file_list (Example):

  [
      {
          'original_path': 'C:/Path/To/AssetA/AssetA_Diffuse.png',
          'predicted_asset_name': 'AssetA',
          'predicted_output_name': 'T_AssetA_BC.tga',
          'status': 'Ignored', # <-- User Edit
          'details': 'User override: Ignored',
          'source_asset': 'AssetA'
      },
      {
          'original_path': 'C:/Path/To/AssetA/AssetA_Normal.png',
          'predicted_asset_name': 'AssetA',
          'predicted_output_name': 'T_AssetA_Normals_DX.tga', # <-- User Edit
          'status': 'Mapped',
          'details': None,
          'source_asset': 'AssetA'
      },
      # ... other files
  ]
  

• asset_properties (Example):

  {
      'AssetA': {
          'asset_category': 'surface',
          'asset_tags': ['wood', 'painted']
      },
      'AssetB': {
          'asset_category': 'model',
          'asset_tags': ['metal', 'sci-fi']
      }
      # ... other assets
  }
  

5. Implications

• PredictionHandler: Needs modification to generate and emit both file_list and asset_properties. Signal signature changes.
• PreviewTableModel: Needs modification to receive, store, and provide both structures. Must implement editing capabilities (flags, setData) for the relevant columns using the file_list. Needs methods like get_edited_data() returning both structures.
• MainWindow: Needs modification to retrieve both structures from the table model and pass them to the ProcessingHandler.
• ProcessingHandler: Needs modification to accept both structures in its processing method signature. Must update logic to use the edited status and predicted_output_name from file_list and look up data in asset_properties using source_asset when needed.