​

Telescope Mode

​

Activating Telescope Mode

1. Click the telescope mode button in the UI
2. The screen will darken with a semi-transparent overlay
3. Click on the sky to set the center of your telescope’s view

• Escape: Exit telescope mode and return to normal view

​

FOV Shapes

​

Circle Mode

• Diameter calculated from the smaller dimension (min of width/height)
• Smooth boundary using 180+ interpolation points for accurate spherical rendering
• Ideal for visual observers

​

Rectangle Mode

• Aspect ratio matches sensor dimensions
• Corners use spherical arc interpolation (36 points per edge)
• Supports rotation for framing flexibility

​

FOV Calculation

​

Sensor-Based FOV

FOV_width = 2 × arctan(sensor_width / (2 × focal_length))
FOV_height = 2 × arctan(sensor_height / (2 × focal_length))

​

Manual FOV Override

• set_manual_fov(width_deg, height_deg): Specify exact angular dimensions
• clear_manual_fov(): Return to sensor-based calculation
• Useful for eyepieces with specified AFOV ratings

​

Aspect Ratio Override

• set_aspect_ratio(ratio): Sets width/height ratio (0.2 to 5.0)
• Useful for cropped sensors or special formats

​

Telescope Parameters

​

Focal Length

• Range: 1mm to infinity
• Default: 250mm
• Controls magnification and field of view
• set_focal_mm(focal_mm): Update telescope focal length

​

Sensor Selection

• set_sensor_key(key): Choose from presets (“tiny”, “aps_c”, “full_frame”)
• Automatically calculates FOV based on focal length

​

Navigation and Movement

​

Movement Modes

• Step size: 0.05 arcminutes (3 arcseconds)
• Hold rate: 0.5 arcminutes per second
• For fine adjustments and high-magnification work

• Step size: 0.05 degrees (3 arcminutes)
• Hold rate: 0.5 degrees per second
• For slewing and coarse positioning

​

Keyboard Navigation

• Up Arrow: Nudge altitude up
• Down Arrow: Nudge altitude down
• Left Arrow: Nudge azimuth left
• Right Arrow: Nudge azimuth right

• Single tap: Discrete step (based on current speed mode)
• Hold key: Continuous movement at configured hold rate
• Movement rate calculated in telescope_scope_mode.py:122-126

​

Mouse Navigation

• Click anywhere on the sky to instantly center the FOV indicator
• Uses screen_to_sky() projection to convert screen coordinates to celestial coordinates

• Click and hold inside the FOV indicator
• Drag to pan the view (camera-like inverse motion)
• Precise for small adjustments

​

Goto Functionality

set_center(sky_coord)  # sky_coord = (alt_deg, az_deg)

• Normalizes altitude to [-89.9°, 89.9°] to avoid pole singularities
• Normalizes azimuth to [0°, 360°)
• Cancels “awaiting click” state

​

Visual Rendering

​

Dark Overlay

• Semi-transparent black overlay (190 alpha)
• Creates “tunnel vision” effect
• Interior remains fully clear for unobstructed view

​

Boundary Rendering

• Subtle white glow (35 alpha, 1.2px width)
• Bright white edge (120 alpha, 0.8px width)
• Anti-aliased for smooth appearance

​

Crosshair

• 8-pixel arm length cross
• Dual-layer rendering (glow + bright core)
• White dot at exact center (1.2px radius)

​

HUD Information

​

Left Panel (Core Scope Info)

FOV: 1.234° (74.0')  |  Movement: SLOW (M)

FOV: 2.100° x 1.400°  |  Movement: FAST (M)

​

Right Panel (Optical Telemetry)

• Exit pupil diameter (mm) - computed from aperture and magnification
• Airmass factor (X) - atmospheric path length multiplier
• Extinction coefficient (k) - magnitude loss per airmass
• Atmospheric transmission (%) - light reaching the telescope

Exit Pupil: 2.4mm
Airmass: 1.15X
Extinction: 0.18 mag/X
Transmission: 94.2%

​

HUD Positioning

• Panels positioned at vertical center of FOV indicator
• Left panel: 12px from left edge
• Right panel: 12px from right edge
• Clamped to viewport bounds to prevent off-screen rendering
• Compact sizing based on actual text width (max 360px)

​

Atmospheric Calculations

​

Airmass

airmass = airmass_from_altitude_deg(h_deg)

​

Extinction Coefficient

• Fetches real-time AOD (Aerosol Optical Depth) from Copernicus CAMS
• Fetches surface pressure data
• Computes k-extinction: extinction_k_mag_per_airmass(aod, pressure_hpa)
• Falls back to k=0.20 if data unavailable

​

Magnitude Loss

loss_mag = k_extinction × (airmass - 1.0)

​

Transmission

transmission = 10^(-0.4 × loss_mag)

​

Exit Pupil Calculation

magnification = telescope_focal_mm / eyepiece_focal_mm
exit_pupil = aperture_mm / magnification

• Below 0.5mm: Diffraction-limited resolution
• Above 7mm: Wasted light (exceeds dark-adapted pupil)

​

Integration with Star Rendering

​

Scope Magnitude Limit

scope_mlim = general_mlim + 5×log10(aperture_mm/pupil_mm)

• general_mlim: Naked-eye limiting magnitude from Bortle class
• Aperture advantage increases magnitude reach
• Computed in telescope_runtime.py:452-478

​

Active Scope Rendering

• Star magnitude limit switches to scope_mlim
• Only stars within FOV boundary rendered at enhanced brightness
• Background stars dimmed by overlay

​

Implementation Details

​

Controller State

• enabled: Boolean flag for active state
• awaiting_center_click: True until first click placement
• shape: “circle” or “rectangle”
• speed_mode: “slow” or “fast”
• center: (alt, az) tuple for current pointing
• dragging: Boolean for mouse drag state

​

Projection

• destination_point(center, bearing, radius): Spherical geometry
• slerp_arc_points(p0, p1, n): Great circle arc interpolation
• Stereographic projection to screen coordinates

​

Coordinate Systems

• Sky Coords: (altitude_deg, azimuth_deg) in horizontal coordinate system
• Screen Coords: (x, y) in pixel coordinates
• Conversion via project_fn and unproject_fn callbacks
• Handles pole singularities and azimuth wrapping