Asset-Frameworker/Tickets/REFACTOR-001-plan.md

Refactoring Plan for REFACTOR-001: Merge Maps From Source

This plan details the steps to implement the refactoring described in Tickets/REFACTOR-001-merge-from-source.md. The goal is to improve merged map quality by loading data directly from original source files, avoiding intermediate compression artifacts.

Final Plan Summary:

1. Implement _load_and_transform_source Helper:

   • Loads source image, performs initial prep (BGR->RGB, gloss inversion), resizes to target resolution.
   • Includes an in-memory cache (passed from process) using a (source_path, resolution_key) key to store and retrieve resized results, avoiding redundant loading and resizing within a single process call.

2. Implement _save_image Helper:

   • Encapsulates all saving logic: determining output format/bit depth based on rules, final data type/color space conversions, filename construction, saving with cv2.imwrite, and fallback logic (e.g., EXR->PNG).

3. Refactor _process_maps (Potential Rename):

   • Modify to process only maps not used as inputs for any merge rule.
   • Calls _load_and_transform_source (passing cache) and _save_image.

4. Replace _merge_maps with _merge_maps_from_source:

   • Iterates through merge rules.
   • Calls _load_and_transform_source (passing cache) for each required source input at target resolutions.
   • Merges the resulting channel data.
   • Calls _save_image to save the final merged map.

5. Update process Method:

   • Initializes an empty cache dictionary (loaded_data_cache = {}) at the beginning of the method.
   • Passes this cache dictionary to all calls to _load_and_transform_source within its scope.
   • Coordinates calls to the refactored/new processing and merging functions.
   • Ensures results are collected correctly for metadata generation.

New Workflow Visualization:

graph TD
    A2[Input Files] --> B2(_inventory_and_classify_files);
    B2 --> C2{Classified Maps Info};

    subgraph Processing Logic
        C2 --> D2(_process_individual_map);
        C2 --> E2(_merge_maps_from_source);
        D2 --> F2([_load_and_transform_source w/ Cache]);
        E2 --> F2;
    end

    F2 --> G2{Loaded/Transformed Data (Cached)};

    subgraph Saving Logic
         G2 --> H2([_save_image]);
         D2 --> H2;
         E2 --> H2;
    end

    H2 -- Saves Temp Files --> I2{Processed/Merged Map Details};

    I2 --> J2(_generate_metadata_file);
    J2 --> K2(_organize_output_files);
## Current Status (as of 2025-04-22 ~19:45 CET)

*   **DONE:** Step 1: Implemented `_load_and_transform_source` helper function (including caching logic) and inserted into `asset_processor.py`.
*   **DONE:** Step 2: Implemented `_save_image` helper function and inserted into `asset_processor.py`.
*   **DONE:** Step 5 (Partial): Updated `process` method to initialize `loaded_data_cache` and updated calls to use new function names (`_process_individual_maps`, `_merge_maps_from_source`) and pass the cache.
*   **DONE:** Renamed function definitions: `_process_maps` -> `_process_individual_maps`, `_merge_maps` -> `_merge_maps_from_source`, and added `loaded_data_cache` parameter.
*   **DONE:** Corrected syntax errors introduced during previous `apply_diff` operations (related to docstrings).

## Remaining Steps:

1.  **DONE:** Modify `_process_individual_maps` Logic: Updated the internal logic to correctly utilize `_load_and_transform_source` (with cache) and `_save_image` for maps not involved in merging.
2.  **DONE:** Modify `_merge_maps_from_source` Logic: Updated the internal logic to correctly utilize `_load_and_transform_source` (with cache) for *source* files, perform the channel merge, and then use `_save_image` for the merged result.
3.  **DONE:** Testing: User confirmed the refactored code works correctly.