{
    "sourceFile": "Project Notes/Data_Structures/Preview_Edit_Interface.md",
    "activeCommit": 0,
    "commits": [
        {
            "activePatchIndex": 0,
            "patches": [
                {
                    "date": 1745853960334,
                    "content": "Index: \n===================================================================\n--- \n+++ \n"
                }
            ],
            "date": 1745853960334,
            "name": "Commit-0",
            "content": "# Data Interface: GUI Preview Edits to Processing Handler\r\n\r\n## 1. Purpose\r\n\r\nThis 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.\r\n\r\n## 2. Data Structures\r\n\r\nTwo primary data structures are used:\r\n\r\n### 2.1. File Data (`file_list`)\r\n\r\n*   **Type:** `list[dict]`\r\n*   **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.\r\n*   **Dictionary Keys (per file):**\r\n    *   `original_path` (`str`): The full path to the source file. (Read-only by GUI)\r\n    *   `predicted_asset_name` (`str | None`): The name of the asset group the file belongs to, derived from input. (Read-only by GUI)\r\n    *   `predicted_output_name` (`str | None`): The backend's predicted final output filename. **EDITABLE** by the user in the GUI ('Predicted Asset' column).\r\n    *   `status` (`str`): The backend's predicted status (e.g., 'Mapped', 'Ignored'). **EDITABLE** by the user in the GUI ('Status' column).\r\n    *   `details` (`str | None`): Additional information or error messages. (Read-only by GUI, potentially updated by model validation).\r\n    *   `source_asset` (`str`): An identifier for the source asset group (e.g., input folder/zip name). (Read-only by GUI)\r\n\r\n### 2.2. Asset Properties (`asset_properties`)\r\n\r\n*   **Type:** `dict[str, dict]`\r\n*   **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).\r\n*   **Asset Properties Dictionary Keys (Example):**\r\n    *   `asset_category` (`str`): The determined category (e.g., 'surface', 'model').\r\n    *   `asset_tags` (`list[str]`): Any relevant tags associated with the asset.\r\n    *   *(Other future asset-level properties can be added here)*\r\n\r\n## 3. Data Flow & Interface\r\n\r\n```mermaid\r\ngraph LR\r\n    subgraph Backend\r\n        A[Prediction Logic] -- Generates --> B(file_list);\r\n        A -- Generates --> C(asset_properties);\r\n    end\r\n\r\n    subgraph GUI Components\r\n        D[PredictionHandler] -- prediction_results_ready(file_list, asset_properties) --> E(PreviewTableModel);\r\n        E -- Stores & Allows Edits --> F(Internal file_list);\r\n        E -- Stores --> G(Internal asset_properties);\r\n        H[MainWindow] -- Retrieves --> F;\r\n        H -- Retrieves --> G;\r\n        H -- Passes (file_list, asset_properties) --> I[ProcessingHandler];\r\n    end\r\n\r\n    subgraph Backend\r\n        I -- Uses Edited --> F;\r\n        I -- Uses Read-Only --> G;\r\n    end\r\n\r\n    style A fill:#lightblue,stroke:#333,stroke-width:1px\r\n    style B fill:#lightgreen,stroke:#333,stroke-width:1px\r\n    style C fill:#lightyellow,stroke:#333,stroke-width:1px\r\n    style D fill:#f9f,stroke:#333,stroke-width:2px\r\n    style E fill:#ccf,stroke:#333,stroke-width:2px\r\n    style F fill:#lightgreen,stroke:#333,stroke-width:1px\r\n    style G fill:#lightyellow,stroke:#333,stroke-width:1px\r\n    style H fill:#f9f,stroke:#333,stroke-width:2px\r\n    style I fill:#lightblue,stroke:#333,stroke-width:2px\r\n\r\n```\r\n\r\n1.  **Prediction:** The `PredictionHandler` generates both the `file_list` and `asset_properties`.\r\n2.  **Signal:** It emits a signal (e.g., `prediction_results_ready`) containing both structures, likely as a tuple `(file_list, asset_properties)`.\r\n3.  **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.\r\n4.  **Processing Trigger:** When the user initiates processing, the `MainWindow` retrieves the (potentially modified) `file_list` and the (unmodified) `asset_properties` from the `PreviewTableModel`.\r\n5.  **Processing Execution:** The `MainWindow` passes both structures to the `ProcessingHandler`.\r\n6.  **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.\r\n\r\n## 4. Example Data Passed to `ProcessingHandler`\r\n\r\n*   **`file_list` (Example):**\r\n    ```python\r\n    [\r\n        {\r\n            'original_path': 'C:/Path/To/AssetA/AssetA_Diffuse.png',\r\n            'predicted_asset_name': 'AssetA',\r\n            'predicted_output_name': 'T_AssetA_BC.tga',\r\n            'status': 'Ignored', # <-- User Edit\r\n            'details': 'User override: Ignored',\r\n            'source_asset': 'AssetA'\r\n        },\r\n        {\r\n            'original_path': 'C:/Path/To/AssetA/AssetA_Normal.png',\r\n            'predicted_asset_name': 'AssetA',\r\n            'predicted_output_name': 'T_AssetA_Normals_DX.tga', # <-- User Edit\r\n            'status': 'Mapped',\r\n            'details': None,\r\n            'source_asset': 'AssetA'\r\n        },\r\n        # ... other files\r\n    ]\r\n    ```\r\n*   **`asset_properties` (Example):**\r\n    ```python\r\n    {\r\n        'AssetA': {\r\n            'asset_category': 'surface',\r\n            'asset_tags': ['wood', 'painted']\r\n        },\r\n        'AssetB': {\r\n            'asset_category': 'model',\r\n            'asset_tags': ['metal', 'sci-fi']\r\n        }\r\n        # ... other assets\r\n    }\r\n    ```\r\n\r\n## 5. Implications\r\n\r\n*   **`PredictionHandler`:** Needs modification to generate and emit both `file_list` and `asset_properties`. Signal signature changes.\r\n*   **`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.\r\n*   **`MainWindow`:** Needs modification to retrieve both structures from the table model and pass them to the `ProcessingHandler`.\r\n*   **`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."
        }
    ]
}