Dimension

Overview

The Dimension class represents 2D dimension structure containing width and height. It's used for layout operations, size calculations, and spatial operations within the MatrixOS framework.

The Dimension class is implemented in Applications/Python/PikaPython/MatrixOS_Dimension.py with type hints in Applications/Python/PikaPython/_MatrixOS_Dimension.pyi.

---

Dimension(*val)

class Dimension:
    def __init__(self, *val) -> None

Creates a dimension using various input formats:

• 0 arguments: Zero dimension (0, 0)
• 1 argument: From raw bytes
• 2 arguments: Width and height

Parameters:

• *val: Variable arguments depending on desired constructor

Examples:

# Create zero dimension
zero_dim = Dimension()

# Create dimension from width and height
size = Dimension(8, 8)  # 8x8 dimension

# Create from raw bytes (advanced usage)
raw_dim = Dimension(0x00080008)  # Packed width/height

---

Getter Methods

X

def X(self) -> int

Gets the X component (width) of the dimension.

Returns:

• int: The width value

Example:

dim = Dimension(8, 6)
width = dim.X()  # Returns 8

Y

def Y(self) -> int

Gets the Y component (height) of the dimension.

Returns:

• int: The height value

Example:

dim = Dimension(8, 6)
height = dim.Y()  # Returns 6

---

Setter Methods

SetX

def SetX(self, x: int) -> None

Sets the X component (width) of the dimension.

Parameters:

• x (int): New width value

Example:

dim = Dimension(8, 6)
dim.SetX(10)  # Dimension is now (10, 6)

SetY

def SetY(self, y: int) -> None

Sets the Y component (height) of the dimension.

Parameters:

• y (int): New height value

Example:

dim = Dimension(8, 6)
dim.SetY(4)  # Dimension is now (8, 4)

---

Methods

Contains

def Contains(self, point: Point) -> bool

Checks if a point is contained within this dimension (from origin).

Parameters:

• point (Point): Point to check

Returns:

• bool: True if point is within dimension bounds

Example:

dim = Dimension(8, 8)
point1 = Point(3, 4)  # Inside
point2 = Point(10, 2)  # Outside

if dim.Contains(point1):
    print("Point is within dimension")

Area

def Area(self) -> int

Calculates the area of the dimension.

Returns:

• int: Area (width × height)

Example:

dim = Dimension(4, 6)
area = dim.Area()  # Returns 24

---

Operators

__add__

def __add__(self, other: Dimension) -> Dimension

Adds two dimensions component-wise.

Parameters:

• other (Dimension): Dimension to add

Returns:

• Dimension: New dimension with added components

Example:

dim1 = Dimension(3, 4)
dim2 = Dimension(2, 1)
result = dim1 + dim2  # Dimension(5, 5)

__eq__

def __eq__(self, other: Dimension) -> bool

Checks if two dimensions are equal.

Parameters:

• other (Dimension): Dimension to compare

Returns:

• bool: True if dimensions are equal

Example:

dim1 = Dimension(8, 8)
dim2 = Dimension(8, 8)
if dim1 == dim2:
    print("Dimensions are equal")

__bool__

def __bool__(self) -> bool

Checks if dimension is non-zero (truthy).

Returns:

• bool: True if dimension has non-zero area

Example:

dim1 = Dimension(0, 0)
dim2 = Dimension(4, 4)

if not dim1:
    print("Zero dimension")

if dim2:
    print("Non-zero dimension")

---

Usage Examples

Basic Dimension Operations

# Create dimensions
grid_size = Dimension(8, 8)
button_size = Dimension(2, 2)
zero_size = Dimension()

# Get components
width = grid_size.X()
height = grid_size.Y()
print(f"Grid size: {width}x{height}")

# Calculate area
total_area = grid_size.Area()
button_area = button_size.Area()
print(f"Grid has {total_area} pixels, button has {button_area}")

# Check containment
center_point = Point(4, 4)
edge_point = Point(7, 7)
outside_point = Point(10, 10)

print(f"Center point in grid: {grid_size.Contains(center_point)}")
print(f"Edge point in grid: {grid_size.Contains(edge_point)}")
print(f"Outside point in grid: {grid_size.Contains(outside_point)}")

Layout Calculations

def fits_in_grid(item_size, grid_size):
    """Check if item fits in grid"""
    return (item_size.X() <= grid_size.X() and
            item_size.Y() <= grid_size.Y())

def calculate_max_items(item_size, grid_size):
    """Calculate maximum items that fit in grid"""
    items_x = grid_size.X() // item_size.X()
    items_y = grid_size.Y() // item_size.Y()
    return items_x * items_y

def get_centered_position(item_size, grid_size):
    """Get position to center item in grid"""
    x = (grid_size.X() - item_size.X()) // 2
    y = (grid_size.Y() - item_size.Y()) // 2
    return Point(x, y)

# Usage examples
grid = Dimension(8, 8)
button = Dimension(2, 2)

if fits_in_grid(button, grid):
    max_buttons = calculate_max_items(button, grid)
    center_pos = get_centered_position(button, grid)
    print(f"Can fit {max_buttons} buttons")
    print(f"Centered button at ({center_pos.X()}, {center_pos.Y()})")

Dimension Arithmetic

# Combine dimensions
total_size = Dimension(4, 4) + Dimension(2, 2)  # Results in (6, 6)

# Create different sized areas
small_area = Dimension(2, 2)
medium_area = Dimension(4, 4)
large_area = Dimension(6, 6)

areas = [small_area, medium_area, large_area]
for i, area in enumerate(areas):
    print(f"Area {i+1}: {area.X()}x{area.Y()} = {area.Area()} pixels")

# Check if dimensions are meaningful
empty_dim = Dimension(0, 0)
valid_dim = Dimension(4, 4)

print(f"Empty dimension is truthy: {bool(empty_dim)}")
print(f"Valid dimension is truthy: {bool(valid_dim)}")

Boundary Checking

def check_all_corners(dimension):
    """Check if all corner points are contained"""
    corners = [
        Point(0, 0),  # Top-left
        Point(dimension.X()-1, 0),  # Top-right
        Point(0, dimension.Y()-1),  # Bottom-left
        Point(dimension.X()-1, dimension.Y()-1)  # Bottom-right
    ]

    for i, corner in enumerate(corners):
        contained = dimension.Contains(corner)
        print(f"Corner {i+1} ({corner.X()}, {corner.Y()}): {contained}")

def get_valid_points(dimension):
    """Get all valid points within dimension"""
    points = []
    for y in range(dimension.Y()):
        for x in range(dimension.X()):
            point = Point(x, y)
            if dimension.Contains(point):
                points.append(point)
    return points

# Test with 8x8 grid
grid_dim = Dimension(8, 8)
check_all_corners(grid_dim)

# Get all valid points (useful for iteration)
valid_points = get_valid_points(Dimension(3, 3))
print(f"3x3 dimension has {len(valid_points)} valid points")

---

Common Patterns

Grid Size Constants

# Standard grid sizes
MATRIX_8X8 = Dimension(8, 8)
MATRIX_4X4 = Dimension(4, 4)
MATRIX_2X2 = Dimension(2, 2)

# UI component sizes
BUTTON_SMALL = Dimension(1, 1)
BUTTON_MEDIUM = Dimension(2, 1)
BUTTON_LARGE = Dimension(3, 2)

# Layout areas
FULL_GRID = Dimension(8, 8)
HALF_GRID = Dimension(4, 8)
QUARTER_GRID = Dimension(4, 4)

Size Validation

def is_valid_dimension(dim, max_dim=Dimension(8, 8)):
    """Validate dimension against maximum size"""
    return (dim.X() > 0 and dim.Y() > 0 and
            dim.X() <= max_dim.X() and dim.Y() <= max_dim.Y())

def clamp_dimension(dim, max_dim=Dimension(8, 8)):
    """Clamp dimension to valid range"""
    x = max(1, min(max_dim.X(), dim.X()))
    y = max(1, min(max_dim.Y(), dim.Y()))
    return Dimension(x, y)

# Example usage
test_dim = Dimension(10, 12)
if not is_valid_dimension(test_dim):
    clamped = clamp_dimension(test_dim)
    print(f"Clamped {test_dim.X()}x{test_dim.Y()} to {clamped.X()}x{clamped.Y()}")