Asset-Frameworker/ProjectNotes/bit_depth_refactor_plan.md

Bit Depth Terminology Refactoring Plan

1. Background

Currently, there's an inconsistency in how bit depth rules and settings are defined and used across the project:

• config/file_type_definitions.json: Uses "bit_depth_rule" with values like "force_8bit" and "respect".
• config/app_settings.json: (Within MAP_MERGE_RULES) uses "output_bit_depth" with values like "respect_inputs".
• processing/utils/image_saving_utils.py: Contains logic that attempts to handle "respect_inputs" but is currently unreachable, and the "respect" rule effectively defaults to 8-bit.

This plan aims to unify the terminology and correct the processing logic.

2. Proposed Unified Terminology

A new configuration key and a clear set of values will be adopted:

• New Key: bit_depth_policy
  • This key will replace "bit_depth_rule" in file_type_definitions.json.
  • This key will replace "output_bit_depth" in app_settings.json (for MAP_MERGE_RULES).
• Values for bit_depth_policy:
  • "force_8bit": Always output 8-bit.
  • "force_16bit": Always output 16-bit.
  • "preserve": If any source image (or any input to a merge operation) has a bit depth greater than 8-bit, the output will be 16-bit. Otherwise, the output will be 8-bit.
  • "" (empty string or null): No specific bit depth policy applies (e.g., for non-image files like models or text files).

3. Refactoring Plan Details

Phase 1: Configuration File Updates

1. config/file_type_definitions.json:
   • Rename all instances of the key "bit_depth_rule" to "bit_depth_policy".
   • Update values:
     • "force_8bit" remains "force_8bit".
     • "respect" changes to "preserve".
     • "" (empty string) remains "".
2. config/app_settings.json:
   • Within each rule in the MAP_MERGE_RULES array, rename the key "output_bit_depth" to "bit_depth_policy".
   • Update the value: "respect_inputs" changes to "preserve".

Phase 2: Code Update - configuration.py

1. Modify the Configuration class:
   • Rename the method get_bit_depth_rule() to get_bit_depth_policy().
   • Update this method to read the new "bit_depth_policy" key from the loaded file type definitions.
   • Ensure it correctly handles and returns the new policy values ("force_8bit", "force_16bit", "preserve", "").
   • The method should continue to provide a sensible default if a map type is not found or has an invalid policy.

Phase 3: Code Update - processing/utils/image_saving_utils.py

1. Refactor the save_image_variants function:
   • It will receive the bit_depth_policy (e.g., "preserve", "force_8bit") via its file_type_defs argument (which originates from the Configuration object).
   • Correct the internal logic for determining target_bit_depth based on the bit_depth_policy argument:
     • If bit_depth_policy == "force_8bit", then target_bit_depth = 8.
     • If bit_depth_policy == "force_16bit", then target_bit_depth = 16.
     • If bit_depth_policy == "preserve":
       • Examine the source_bit_depth_info argument (list of bit depths of input images).
       • If any source bit depth in source_bit_depth_info is greater than 8, then target_bit_depth = 16.
       • Otherwise (all source bit depths are 8 or less, or list is empty/all None), target_bit_depth = 8.
     • If bit_depth_policy == "" or is null (or any other unhandled value), a clear default behavior should be established (e.g., log a warning and default to "preserve" or skip bit depth adjustments if appropriate for the file type).

Phase 4: Code Update - processing/pipeline/stages/merged_task_processor.py

1. This stage is largely unaffected in its core logic for collecting input_source_bit_depths.
2. The ProcessedMergedMapData object it produces will continue to carry these source_bit_depths.
3. When this data is later passed to the SaveVariantsStage (and subsequently to save_image_variants), the internal_map_type of the merged map (e.g., "MAP_NRMRGH") will be used. The Configuration object will provide its bit_depth_policy (which, after refactoring file_type_definitions.json, should be "preserve" for relevant merged maps).
4. The refactored save_image_variants will then use this "preserve" policy along with the source_bit_depth_info (derived from the merge inputs) to correctly determine the output bit depth for the merged map.

Phase 5: Review Other Code & Potential Impacts

1. Conduct a codebase search for any remaining direct usages of the old keys ("bit_depth_rule", "output_bit_depth") or their values.
2. Update these locations to use the new Configuration.get_bit_depth_policy() method and the new "bit_depth_policy" key and values.
3. Pay special attention to any prediction logic (e.g., in gui/prediction_handler.py or gui/llm_prediction_handler.py) if it currently considers or tries to infer bit depth rules.

4. Backward Compatibility & Migration

• This is a breaking change for existing user-customized configuration files (file_type_definitions.json, app_settings.json, and any custom presets).
• Recommended Approach: Implement migration logic within the Configuration class's loading methods.
  • When loading file_type_definitions.json: If "bit_depth_rule" is found, convert its value (e.g., "respect" to "preserve") and store it under the new "bit_depth_policy" key. Log a warning.
  • When loading app_settings.json (specifically MAP_MERGE_RULES): If "output_bit_depth" is found, convert its value (e.g., "respect_inputs" to "preserve") and store it under "bit_depth_policy". Log a warning.
  • This ensures the application can still function with older user configs while guiding users to update.

5. Visualized Logic for save_image_variants (Post-Refactor)

graph TD
    A[Start save_image_variants] --> B{Get bit_depth_policy for base_map_type};
    B --> C{Policy is "force_8bit"?};
    C -- Yes --> D[target_bit_depth = 8];
    C -- No --> E{Policy is "force_16bit"?};
    E -- Yes --> F[target_bit_depth = 16];
    E -- No --> G{Policy is "preserve"?};
    G -- Yes --> H{Any source_bit_depth_info > 8?};
    H -- Yes --> I[target_bit_depth = 16];
    H -- No --> J[target_bit_depth = 8];
    G -- No --> K[Log warning: Unknown policy or "" policy, default to 8-bit or handle as per type];
    K --> D;
    D --> L[Proceed to save with 8-bit];
    F --> M[Proceed to save with 16-bit];
    I --> M;
    J --> L;
    L --> Z[End];
    M --> Z;

This plan aims to create a more consistent, understandable, and correctly functioning system for handling bit depth across the application.