docs/FRACTAL_ADDRESSING.md

Fractal Coordinate Decoder - Implementation Guide

Overview

The Fractal Coordinate Decoder maps 32-bit Heat Codes to spatial coordinates using quadtree descent. This enables non-linear, fractal distribution of atom updates across the canvas, creating the "Infinite Canvas" capability.

Algorithm: resolve_fractal_address()

Input

• heat_code_int: 32-bit integer (from 4-byte Heat Code)
• canvas_size: (width, height) tuple

Process

1. Initialize: Start with full canvas rectangle (0, 0, canvas_width, canvas_height)

2. Descent Loop: For each of 16 levels (MSB to LSB):

   • Extract 2-bit pair from heat code
   • Map to quadrant:
     • 00 → Top-Left (no translation)
     • 01 → Top-Right (x += w/2)
     • 10 → Bottom-Left (y += h/2)
     • 11 → Bottom-Right (x += w/2, y += h/2)
   • Subdivide: w /= 2, h /= 2

3. Termination: Stop when:

   • Region size ≤ minimum bucket size (64px), OR
   • Stop sequence detected (consecutive 0000 after level 8)

4. Output: ZoneRect (x, y, width, height) defining exact spatial region

Bit Structure

32-bit Heat Code: [31:30] [29:28] [27:26] ... [3:2] [1:0]
                   Level 1  Level 2  Level 3 ... Level 15 Level 16

Each 2-bit pair selects a quadrant at that quadtree level.

Example

Heat Code: 0x80000000 (MSB set)

• Level 1 (bits 31-30): 10 → Bottom-Left → y += h/2
• Level 2 (bits 29-28): 00 → Top-Left → no translation
• ... continues descending until bucket size reached

Result: Zone in bottom-left quadrant of canvas.

Integration

In LogosDisplayInterpreter

# Decode bucket position
bucket_x, bucket_y = display_interpreter.decode_bucket_position(heat_code_hex)

# Get exact zone rectangle
zone_rect = display_interpreter.get_fractal_zone_rect(heat_code_hex)

In LogosFractalEngine

# Direct fractal addressing
zone_rect = fractal_engine.resolve_fractal_address(heat_code_int, canvas_size)

# Bucket coordinate mapping
bucket_x, bucket_y = fractal_engine.fractal_to_bucket_coords(
    heat_code_int, num_buckets_x, num_buckets_y
)

Benefits

1. Non-Linear Distribution: Updates occur in fractal pattern, not sequential
2. Infinite Canvas: Supports up to 2^16 × 2^16 resolution (65,536 × 65,536)
3. Scalable Addressing: Same heat code maps to different regions at different scales
4. Deterministic: Same heat code always maps to same region

Test Results

See coordinate_decoder_test.py for validation:

• 00000000 → Top-Left region
• FFFFFFFF → Bottom-Right region
• 80000000 → Bottom-Left path (top-right quadrant of left half)
• Each heat code maps to distinct spatial region

Technical Notes

• Minimum Bucket Size: 64px (configurable)
• Maximum Depth: 16 levels (2^16 = 65,536 subdivisions)
• Stop Sequence: Early termination on 0000 after level 8
• Coordinate Clamping: Final ZoneRect clamped to canvas bounds