16 bit processing fixes + code unification
This commit is contained in:
105
ProjectNotes/bit_depth_refactor_plan.md
Normal file
105
ProjectNotes/bit_depth_refactor_plan.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user