56 lines
3.5 KiB
Markdown
56 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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. |