# 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:

```mermaid
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.