Asset-Frameworker/ProjectNotes/OUTPUT_FORMAT_PLAN_v2.md

Revised Plan: Implement Input-Based Output Format Logic with JPG Threshold Override

This plan outlines the steps to modify the Asset Processor Tool to determine the output format of texture maps based on the input file format, specific rules, and a JPG resolution threshold override.

Requirements Summary (Revised)

Based on user clarifications:

1. JPG Threshold Override: If the target output bit depth is 8-bit AND the image resolution is greater than or equal to RESOLUTION_THRESHOLD_FOR_JPG (defined in config.py), the output format must be JPG.
2. Input-Based Logic (if threshold not met):
   • JPG Input -> JPG Output: If the original source map is JPG and the target is 8-bit (and below threshold), output JPG.
   • TIF Input -> PNG/EXR Output: If the original source map is TIF:
     • If target is 16-bit, output EXR or PNG based on OUTPUT_FORMAT_16BIT_PRIMARY config.
     • If target is 8-bit (and below threshold), output PNG.
   • Other Inputs (PNG, etc.) -> Configured Output: For other input formats (and below threshold if 8-bit):
     • If target is 16-bit, output EXR or PNG based on OUTPUT_FORMAT_16BIT_PRIMARY config.
     • If target is 8-bit, output PNG (or format specified by OUTPUT_FORMAT_8BIT).
3. force_8bit Rule: If a map type has a force_8bit rule, the target bit depth is 8-bit. The output format will then be determined by the JPG threshold override or the input-based logic (resulting in JPG or PNG).
4. Merged Maps:
   • Determine target output_bit_depth from the merge rule (respect_inputs, force_8bit, etc.).
   • Check JPG Threshold Override: If target output_bit_depth is 8-bit AND resolution >= threshold, the final output format is JPG.
   • Else (Hierarchy Logic): Determine the highest format among original inputs (EXR > TIF > PNG > JPG).
     • If highest was TIF, adjust based on target bit depth (16-bit -> EXR/PNG config; 8-bit -> PNG).
     • Otherwise, use the highest format found (EXR, PNG, JPG).
   • JPG 8-bit Check: If the final format is JPG but the target bit depth was 16, force the merged data to 8-bit before saving.
5. JPG Resizing: Resized JPGs will be saved as JPG if the logic determines JPG as the output format.

Implementation Plan (Revised)

Phase 1: Data Gathering Enhancement (Already Done & Correct)

• _inventory_and_classify_files stores the original file extension in self.classified_files["maps"].

Phase 2: Modify _process_maps

1. Retrieve the original_extension from map_info.
2. Determine the target output_bit_depth (8 or 16).
3. Get the threshold = self.config.resolution_threshold_for_jpg.
4. Get the target_dim for the current resolution loop iteration.
5. New Format Logic (Revised):
   • Initialize output_format, output_ext, save_params, needs_float16.
   • Check JPG Threshold Override:
     • If output_bit_depth == 8 AND target_dim >= threshold: Set format to JPG, set JPG params.
   • Else (Apply Input/Rule-Based Logic):
     • If bit_depth_rule == 'force_8bit': Set format to PNG (8-bit), set PNG params.
     • Else if original_extension == '.jpg' and output_bit_depth == 8: Set format to JPG, set JPG params.
     • Else if original_extension == '.tif':
       • If output_bit_depth == 16: Set format to EXR/PNG (16-bit config), set params, set needs_float16 if EXR.
       • If output_bit_depth == 8: Set format to PNG, set PNG params.
     • Else (other inputs like .png):
       • If output_bit_depth == 16: Set format to EXR/PNG (16-bit config), set params, set needs_float16 if EXR.
       • If output_bit_depth == 8: Set format to PNG (8-bit config), set PNG params.
6. Proceed with data type conversion and saving.

Phase 3: Modify _merge_maps

1. Retrieve original extensions of inputs (input_original_extensions).
2. Determine target output_bit_depth from the merge rule.
3. Get the threshold = self.config.resolution_threshold_for_jpg.
4. Get the target_dim for the current resolution loop iteration.
5. New Format Logic (Revised):
   • Initialize final_output_format, output_ext, save_params, needs_float16.
   • Check JPG Threshold Override:
     • If output_bit_depth == 8 AND target_dim >= threshold: Set final_output_format = 'jpg'.
   • Else (Apply Hierarchy/Rule-Based Logic):
     • Determine highest_input_format (EXR > TIF > PNG > JPG).
     • Start with final_output_format = highest_input_format.
     • If highest_input_format == 'tif': Adjust based on target bit depth (16->EXR/PNG config; 8->PNG).
   • Set output_format = final_output_format.
   • Set output_ext, save_params, needs_float16 based on output_format.
   • JPG 8-bit Check: If output_format == 'jpg' and output_bit_depth == 16, force final merged data to 8-bit before saving and update output_bit_depth variable.
6. Proceed with merging, data type conversion, and saving.

Phase 4: Configuration and Documentation

1. Modify config.py: Ensure RESOLUTION_THRESHOLD_FOR_JPG is uncommented and set correctly (revert previous change).
2. Update readme.md: Clarify the precedence: 8-bit maps >= threshold become JPG, otherwise the input-based logic applies.

Visual Plan (Mermaid - Revised)

graph TD
    A[Start] --> B(Phase 1: Enhance Classification - Done);
    B --> C(Phase 2: Modify _process_maps);
    C --> C1(Get original extension);
    C --> C2(Determine target bit depth);
    C --> C3(Get target_dim & threshold);
    C --> C4{8bit AND >= threshold?};
    C4 -- Yes --> C4a[Format=JPG];
    C4 -- No --> C5(Apply Input/Rule Logic);
    C5 -- force_8bit --> C5a[Format=PNG];
    C5 -- input=.jpg, 8bit --> C5b[Format=JPG];
    C5 -- input=.tif, 16bit --> C5c[Format=EXR/PNG (Config)];
    C5 -- input=.tif, 8bit --> C5d[Format=PNG];
    C5 -- input=other, 16bit --> C5c;
    C5 -- input=other, 8bit --> C5e[Format=PNG (Config)];
    C4a --> C6(Set Save Params & Save);
    C5a --> C6;
    C5b --> C6;
    C5c --> C6;
    C5d --> C6;
    C5e --> C6;
    C6 --> D(Phase 3: Modify _merge_maps);
    D --> D1(Get original extensions of inputs);
    D --> D2(Determine target bit depth from rule);
    D --> D3(Get target_dim & threshold);
    D --> D4{8bit AND >= threshold?};
    D4 -- Yes --> D4a[FinalFormat=JPG];
    D4 -- No --> D5(Apply Hierarchy Logic);
    D5 --> D5a(Find highest input format);
    D5a --> D5b{Highest = TIF?};
    D5b -- Yes --> D5c{Target 16bit?};
    D5c -- Yes --> D5d[FinalFormat=EXR/PNG (Config)];
    D5c -- No --> D5e[FinalFormat=PNG];
    D5b -- No --> D5f[FinalFormat=HighestInput];
    D4a --> D6(Set Save Params);
    D5d --> D6;
    D5e --> D6;
    D5f --> D6;
    D6 --> D7{Format=JPG AND Target=16bit?};
    D7 -- Yes --> D7a(Force data to 8bit);
    D7 -- No --> D8(Save Merged);
    D7a --> D8;
    D8 --> E(Phase 4: Config & Docs);
    E --> E1(Uncomment threshold in config.py);
    E --> E2(Update readme.md);
    E2 --> F[End];