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

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