[REFACTOR-001]: Refactor Map Merging to Use Source Files Directly

Description

Currently, the _merge_maps function in asset_processor.py loads map data from temporary files that have already been processed by _process_maps (resized, format converted, etc.). This intermediate save/load step can introduce quality degradation, especially if the intermediate files are saved using lossy compression (e.g., JPG) or if bit depth conversions occur before merging. This is particularly noticeable in merged maps like NRMRGH where subtle details from the source Normal map might be lost or altered due to recompression.

Goals

Improve Quality: Modify the map merging process to load channel data directly from the selected original source files (after classification and 16-bit prioritization) instead of intermediate processed files, thus avoiding potential quality loss from recompression.
Maintain Modularity: Refactor the processing logic to avoid significant code duplication between individual map processing and the merging process.
Preserve Functionality: Ensure all existing functionality (resizing, gloss inversion, format/bit depth rules, merging logic) is retained and applied correctly in the new structure.

Proposed Solution: Restructure with Helper Functions

Introduce two helper functions within the AssetProcessor class:

_load_and_transform_source(source_path_rel, map_type, target_resolution_key):
- Responsible for loading the specified source file.
- Performs initial preparation: BGR->RGB conversion, Gloss->Roughness inversion (if applicable), MASK extraction (if applicable).
- Resizes the prepared data to the target resolution.
- Returns the resized NumPy array and original source dtype.
_save_image(image_data, map_type, resolution_key, asset_base_name, source_info, output_bit_depth_rule, temp_dir):
- Encapsulates all logic for saving an image.
- Determines final output format and bit depth based on rules and source info.
- Performs final data type conversions (e.g., to uint8, uint16, float16).
- Performs final color space conversion (RGB->BGR for non-EXR).
- Constructs the output filename.
- Saves the image using cv2.imwrite, including fallback logic (e.g., EXR->PNG).
- Returns details of the saved temporary file.

Modified Workflow:

graph TD
    A[Input Files] --> B(_inventory_and_classify_files);
    B --> C{Selected Source Maps Info};

    subgraph Core Processing Logic
        C --> PIM(_process_individual_map);
        C --> MFS(_merge_maps_from_source);
        PIM --> LTS([_load_and_transform_source]);
        MFS --> LTS;
    end

    LTS --> ImgData{Loaded, Prepared, Resized Image Data};

    subgraph Saving Logic
        PIM --> SI([_save_image]);
        MFS --> SI;
        ImgData --> SI; // Pass image data to save helper
    end

    SI --> SaveResults{Saved Temp File Details};

    SaveResults --> Results(Processing Results); // Collect results from saving

    Results --> Meta(_generate_metadata_file);
    Meta --> Org(_organize_output_files);
    Org --> Final[Final Output Structure];

Function Changes:

_process_maps was renamed to _process_individual_map, responsible only for maps not used in merges. It calls _load_and_transform_source and _save_image.
_merge_maps was replaced by _merge_maps_from_source. It identifies required source paths, calls _load_and_transform_source for each input at each target resolution, merges the results, determines saving parameters, and calls _save_image.
The main process loop coordinates calls to the new functions and handles caching.

Resolution (2025-04-22)

The refactoring described above was implemented in asset_processor.py. The _merge_maps_from_source function now utilizes the _load_and_transform_source and _save_image helpers, loading data directly from the classified source files instead of intermediate processed files. User testing confirmed the changes work correctly and improve merged map quality.

Acceptance Criteria (Optional)

Merged maps (e.g., NRMRGH) are generated correctly using data loaded directly from selected source files.
Visual inspection confirms improved quality/reduced artifacts in merged maps compared to the previous method.
Individual maps (not part of any merge rule) are still processed and saved correctly.
All existing configuration options (resolutions, bit depth rules, format rules, gloss inversion) function as expected within the new structure.
Processing time remains within acceptable limits (potential performance impact of repeated source loading/resizing needs monitoring).
Code remains modular and maintainable, with minimal duplication of core logic.

5.0 KiB Raw Blame History