Asset-Frameworker/Tickets/Resolved/FEAT-011-pot-resizing.md

Ticket: FEAT-011 - Implement Power-of-Two Texture Resizing

Status: Open Priority: High Assignee: TBD Reporter: Roo (Architect Mode)

Description

The current asset processing pipeline resizes textures based on a target maximum dimension (e.g., 4K = 4096px) while maintaining the original aspect ratio. This results in non-power-of-two (NPOT) dimensions for non-square textures, which is suboptimal for rendering performance and compatibility with certain systems.

This feature implements a "Stretch/Squash" approach to ensure all output textures have power-of-two (POT) dimensions for each target resolution key.

Proposed Solution

1. Resizing Logic Change:

   • Modify the calculate_target_dimensions helper function in asset_processor.py.
   • Step 1: Calculate intermediate dimensions (scaled_w, scaled_h) by scaling the original image (orig_w, orig_h) to fit within the target resolution key's maximum dimension (e.g., 4096 for "4K") while maintaining the original aspect ratio (using existing logic).
   • Step 2: Implement a new helper function get_nearest_pot(value: int) -> int to find the closest power-of-two value for a given integer.
   • Step 3: Apply get_nearest_pot() to scaled_w to get the final target power-of-two width (pot_w).
   • Step 4: Apply get_nearest_pot() to scaled_h to get the final target power-of-two height (pot_h).
   • Step 5: Return (pot_w, pot_h) from calculate_target_dimensions. The _process_maps function will then use these POT dimensions in cv2.resize.

2. Helper Function get_nearest_pot:

   • This function will take an integer value.
   • It will find the powers of two immediately below (lower_pot) and above (upper_pot) the value.
   • It will return the power of two that is numerically closer to the original value. (e.g., get_nearest_pot(1365) would return 1024, as 1365 - 1024 = 341 and 2048 - 1365 = 683).

3. Filename Convention:

   • The original resolution tag (e.g., _4K, _2K) defined in config.py will be kept in the output filename, even though the final dimensions are POT. This maintains consistency with the processing target.

4. Metadata:

   • The existing aspect ratio change metadata calculation (_normalize_aspect_ratio_change) will remain unchanged. This metadata can be used downstream to potentially correct the aspect ratio distortion introduced by the stretch/squash resizing.

Implementation Diagram

graph TD
    A[Original Dimensions (W, H)] --> B{Target Resolution Key (e.g., "4K")};
    B --> C{Get Max Dimension (e.g., 4096)};
    A & C --> D[Calculate Scaled Dimensions (scaled_w, scaled_h) - Maintain Aspect Ratio];
    D --> E[scaled_w];
    D --> F[scaled_h];
    E --> G[Find Nearest POT(scaled_w) -> pot_w];
    F --> H[Find Nearest POT(scaled_h) -> pot_h];
    G & H --> I[Final POT Dimensions (pot_w, pot_h)];
    I --> J[Use (pot_w, pot_h) in cv2.resize];

Acceptance Criteria

• All textures output by the _process_maps function have power-of-two dimensions (width and height are both powers of 2).
• The resizing uses the "Stretch/Squash" method based on the nearest POT value for each dimension calculated after initial aspect-preserving scaling.
• The output filename retains the original resolution key (e.g., _4K).
• The get_nearest_pot helper function correctly identifies the closest power of two.
• The aspect ratio metadata calculation remains unchanged.