Space Adapter
The space adapter module provides utilities for transforming between screen space and logical (complex plane) coordinates. This is essential for complex analysis visualizations where mouse coordinates need to be converted to mathematical coordinates.
Overview
Screen space and logical space differ in several ways:
Screen space: Origin at top-left, Y increases downward, units are pixels
Logical space: Complex plane, Y increases upward, units are mathematical
The SpaceAdapter handles these differences transparently.
TransformParams
- class analytic_continuation.TransformParams[source]
Bases:
objectParameters defining the screen-to-logical coordinate transformation.
Screen space: origin at top-left, Y increases downward, pixel units Logical space: complex plane, Y increases upward, mathematical units
- The transform is:
logical_x = (screen_x - offset_x) / scale_x logical_y = (offset_y - screen_y) / scale_y (note Y flip)
- Or equivalently:
screen_x = logical_x * scale_x + offset_x screen_y = offset_y - logical_y * scale_y
- classmethod from_view_bounds(screen_width, screen_height, logical_x_range, logical_y_range, uniform=True)[source]
Create transform params from screen dimensions and logical view bounds.
- Parameters:
screen_width (float) – Screen dimensions in pixels
screen_height (float) – Screen dimensions in pixels
logical_x_range (tuple) – (x_min, x_max) in logical coordinates
logical_y_range (tuple) – (y_min, y_max) in logical coordinates
uniform (bool) – If True, use the same scale for both axes (may add margins)
- Return type:
The transform is defined by:
offset: Screen coordinates of the logical origin (0, 0)
scale: Pixels per logical unit
The mathematical relationship is:
logical_x = (screen_x - offset_x) / scale_x
logical_y = (offset_y - screen_y) / scale_y # Note Y flip
Creating from View Bounds
A common use case is creating transform parameters from desired view bounds:
params = TransformParams.from_view_bounds(
screen_width=800,
screen_height=600,
logical_x_range=(-2, 2),
logical_y_range=(-1.5, 1.5),
uniform=True, # Preserve aspect ratio
)
SpaceAdapter
- class analytic_continuation.SpaceAdapter[source]
Bases:
objectTransforms coordinates between screen space and logical (complex plane) space.
- Screen space:
Origin at top-left
X increases rightward
Y increases downward
Units are pixels
- Logical space:
Complex plane
X is the real axis
Y is the imaginary axis (increases upward)
Units are mathematical units
- Parameters:
params (
Optional[TransformParams])
- __init__(params=None)[source]
Initialize the space adapter.
- Parameters:
params (TransformParams, optional) – Transform parameters. If None, uses identity transform.
- screen_to_logical(screen_x, screen_y)[source]
Transform a point from screen space to logical space.
- logical_to_screen(logical_x, logical_y)[source]
Transform a point from logical space to screen space.
- transform_points_to_logical(points)[source]
Transform a list of points from screen to logical space.
- transform_points_to_screen(points)[source]
Transform a list of points from logical to screen space.
- transform_spline_export_to_logical(export)[source]
Transform a full SplineExport from screen to logical space.
Transforms all point arrays (controlPoints, spline, adaptivePolyline). Also scales the parameters.minDistance accordingly.
- Parameters:
export (
SplineExport)- Return type:
- screen_distance_to_logical(screen_distance)[source]
Convert a distance from screen units to logical units.
For non-uniform scaling, uses the geometric mean of scale factors.
- logical_distance_to_screen(logical_distance)[source]
Convert a distance from logical units to screen units.
For non-uniform scaling, uses the geometric mean of scale factors.
- with_params(**kwargs)[source]
Create a new SpaceAdapter with modified parameters.
- Parameters:
**kwargs – Parameters to override (offset_x, offset_y, scale_x, scale_y)
- Returns:
New adapter with modified parameters
- Return type:
- zoom(factor, center_screen=None)[source]
Create a new adapter with zoomed view.
- Parameters:
- Return type:
- pan(delta_screen_x, delta_screen_y)[source]
Create a new adapter with panned view.
- Parameters:
- Return type:
Basic Usage
from analytic_continuation import SpaceAdapter, TransformParams
# Create adapter with default parameters (identity transform)
adapter = SpaceAdapter()
# Or with custom parameters
params = TransformParams(offset_x=400, offset_y=300, scale_x=100)
adapter = SpaceAdapter(params)
# Transform coordinates
lx, ly = adapter.screen_to_logical(450, 250) # (0.5, 0.5)
sx, sy = adapter.logical_to_screen(0.5, 0.5) # (450, 250)
Working with Complex Numbers
# Direct conversion to/from complex numbers
z = adapter.screen_to_complex(500, 200)
screen_coords = adapter.complex_to_screen(1 + 2j)
Transforming Points and Splines
from analytic_continuation import Point, Spline
# Transform individual points
screen_point = Point(x=400, y=300)
logical_point = adapter.transform_point_to_logical(screen_point)
# Transform entire splines
screen_spline = Spline(points=[Point(0, 0), Point(100, 100)], closed=True)
logical_spline = adapter.transform_spline_to_logical(screen_spline)
Zoom and Pan
# Zoom in by 2x around center of screen
zoomed = adapter.zoom(factor=2.0, center_screen=(400, 300))
# Pan by 50 pixels right and 30 pixels down
panned = adapter.pan(delta_screen_x=50, delta_screen_y=30)
Distance Conversion
# Convert screen distance to logical distance
logical_dist = adapter.screen_distance_to_logical(100) # 100 pixels
# Convert logical distance to screen distance
screen_dist = adapter.logical_distance_to_screen(1.0) # 1 unit