Horizon Studio (for N.I.N.A.)

Horizon Studio is a professional-grade tool for creating, editing, and calibrating local horizon profiles in Nighttime Imaging 'N' Astronomy (N.I.N.A.).

---

📖 Introduction & Core Architecture

Traditional methods of mapping a local horizon require guessing where trees, rooftops, or distant mountains intersect the night sky. Horizon Studio eliminates this guesswork by allowing you to trace your actual, physical horizon using a live video feed, generating a native N.I.N.A. .hrz file that prevents your telescope from slewing into obstructions.

The plugin is designed around four key core capabilities:

1. Wide-Angle Webcam Integration (Primary Source): Designed primarily to utilize a wide-angle USB webcam mounted parallel to your telescope. This provides immediate, real-time daylight spatial awareness of your local obstructions. It features Equatorial Counter-Rotation (compensating for field rotation in real-time as your mount slews, keeping the physical ground level) and Interactive Live Zoom (1.0x to 3.0x) for precise positioning.
   • Fallback Main Camera Support: For setups without a webcam (or for users who choose not to add one to their rigs), you can use your main astronomical imaging camera to capture looping exposure feeds with auto-exposure ADU scaling and a real-time star-count overlay.
2. Alt-Az Jogging Simulation on Equatorial Mounts: Tracing a level horizon with an equatorial mount is notoriously difficult because standard mount controls move along RA/Dec lines (which tilt across the sky). Horizon Studio handles this by simulating Alt-Az steps—giving you a virtual 5x5 Jog Grid that moves the mount directly along altitude and azimuth vectors by automatically translating Alt-Az coordinates in real-time, allowing you to walk levelly across roof lines and tree lines.
3. Interactive Sky Dome & Eyepiece Mapping: Features a circular telescope eyepiece HUD view and a 2D Polar Sky Dome Radar. You can double-click anywhere on the eyepiece overlay or click on the radar to slew directly to that sky position. You can easily select, add, or delete nodes, and step through them sequentially clockwise (Slew CW ▶) or counter-clockwise (◀ Slew CCW) by azimuth proximity.
4. 3D Profile Warping & 3D Tilt Correction (Align & Calibrate): One of the plugin's most powerful capabilities. Tracing a horizon is best done during the day when obstructions are clearly visible, but polar aligning your mount at night shifts the coordinate grid, meaning your saved profile no longer matches the sky. 3D Tilt Correction allows you to automatically warp, tilt, and shift the entire horizon profile based on:
   • Horizon Sync (using a saved horizon pin) or Landmark Sync (using permanent landmarks): Perfect for when you load a saved horizon profile from a previous session and the physical setup has changed (e.g., the tripod legs were placed slightly differently, introducing a new physical tilt and rotation).
   • Polar Alignment Sync (Auto-Detect): Automatically retrieves polar alignment errors from N.I.N.A. logs to warp the profile. Note: This method is only valid if the horizon profile was built/edited and polar alignment was completed during the same session without physically moving the mount/tripod (i.e. calibrating the refined polar axis on the exact same physical footing).

---

✨ Implemented Features

🔄 Webcam Co-Alignment, Rotation & Zoom

• Co-Alignment Assistant: Sync the webcam's optical axis with your main telescope by centering a landmark in the main camera and clicking the same target in the webcam feed.
• Equatorial Counter-Rotation: Computes parallactic angles dynamically using mount coordinates, pier side telemetry, and observer latitude to rotate the video feed in real-time, keeping the ground level.
• Interactive Live Zoom: Magnify the live webcam feed from 1.0x to 3.0x using a dedicated slider, making fine-grained landmark target clicks during co-alignment easy without affecting optical offset precision.

📐 Alt-Az Jogging Simulation

• 5x5 Directional Jog Grid: Move your telescope in precise altitude and azimuth increments. The plugin automatically converts Alt-Az steps into equatorial slews on the fly.
• Exact Position Micro-Jumps: Automatically measures settling drift and applies a predictive lead to execute precise micro-adjustments, canceling out mount drift errors.

🌐 3D Profile Warping & 3D Tilt Correction

• Profile Synchronization: Warps the entire horizon profile dynamically using 3D cosine-tilt correction: $$\Delta\text{Alt}{\text{warp}} = \Delta\text{Alt}{\text{ref}} \cdot \cos\left((\text{NodeAz} - \text{RefAz}) \cdot \frac{\pi}{180^\circ}\right)$$
• Horizon Sync: Select any existing horizon pin, slew to it, center the physical obstruction in your eyepiece, and calibrate the entire profile.
• Landmark Sync: Save permanent terrestrial landmarks (e.g. antenna tips, church steeples) that sit above/below the horizon, and use them to recalibrate the profile in future sessions (e.g., after polar alignment or mount teardown).
• Polar Alignment Sync (Auto-Detect): Scans N.I.N.A. log files to auto-detect alignment errors calculated by polar alignment plugins (such as Three Point Polar Alignment or 2-Point Polar Alignment) and automatically warps the entire profile to match the aligned sky.

🕹️ Interactive Eyepiece View & Click-to-Slew

• Circular Eyepiece HUD: Clips the camera view into a clean telescope eyepiece circular overlay.
• Live AR Overlays: Projects the polar radar grid, cardinal directions, active obstruction lines, and mount crosshairs directly onto the live feed.
• Click-to-Slew Navigation: Double-click on the camera HUD or click on the Sky Dome Radar to slew the telescope.
• Sequential Traversal: Step through saved pins and landmarks clockwise or counter-clockwise by physical azimuth proximity, automatically updating the active selection.

📷 Main Camera Integration (Fallback Mode)

• Astronomical Camera Feeds: Integrates with N.I.N.A.'s primary camera system to capture looping exposure feeds.
• Auto-Exposure ADU Scaling: Automatically scales exposure times to maintain a targeted ADU brightness level.
• Star Detection Telemetry: Computes and overlays star counts and median HFR (Half Flux Radius) on the live HUD in real-time.
• Aborts & Driver Protection: Handles exposure interruptions and hardware serialization to protect camera drivers during feed transitions.
• Live Video / Night-Vision Optimization Guidelines:
  • Daytime Live Mapping: High binning (e.g. 3x3 or 4x4) significantly reduces image size, allowing for the fastest possible USB download and rendering speeds (closest to a live video stream). However, because astronomical cameras are highly sensitive, high binning in daylight might cause sensor over-exposure/saturation (solid white images). To prevent this, you can reduce the camera Gain (e.g., to 0), reduce the Binning mode (e.g., to 2x2 or 1x1), or attach a physical Neutral Density (ND) filter to the telescope.
  • Night-Vision Horizon Viewing: To view background horizon features (e.g. trees, power lines, houses) in the dark, enable Auto-Exposure and set a high Gain and high Binning (e.g. 3x3 or 4x4). The auto-exposure system will dynamically scale the exposure to act as a night-vision booster.
  • Star Detection Mode: If you wish to run star detection and HFR measurements at night, disable Auto-Exposure to manually set optimal exposure and gain values (avoiding saturation), and ensure the telescope is in good focus to get an accurate star count. Star detection is automatically bypassed when Auto-Exposure is active to maximize the frame refresh rate.
  • Color Preview (Debayering): For One-Shot Color (OSC) cameras, enabling the Color Preview checkbox in the Main Camera configuration panel debayers the raw monochrome frames into color in real-time. This option is disabled by default to maximize the frame rate and save CPU resources, but during daylight mapping it allows you to see physical horizon obstacles in full color.

🛠️ Horizon Pin Management & File Export

• Dynamic Pin Dropping: Drop nodes at your mount's position to build the horizon profile in real-time. Pins are automatically kept sorted by Azimuth.
• Point Editing & Deletion: Select any node to view its coordinates, slew to it, or delete it from the profile.
• SkySafari PNG Export: Save your profile as an equirectangular PNG, rendering your obstructions in 70% semi-transparent dark blue bounded by a solid red line for SkySafari mobile devices.
• Stellarium Landscape Export: Save your profile as a standard landscape.ini file containing the Alt-Az polygonal coordinate vertices. This can be copied directly into Stellarium's user landscapes directory for immediate visualization of your local horizon bounds.
• Cartes du Ciel (CdC) Compatibility: Standard .hrz profiles can be imported directly into Cartes du Ciel as a local horizon coordinate chart.

---

🛠️ Requirements

• N.I.N.A. (Version 3.0 or higher)
• An equatorial mount connected via ASCOM/Alpaca
• A wide-angled DirectShow USB Webcam (Highly Recommended for macro spatial awareness and fast mapping) OR your main imaging camera (via N.I.N.A. integration)
  • 📱 Smartphone as a Webcam: You can use your smartphone (iOS or Android) as a high-quality wireless camera feed! We highly recommend using Iriun Webcam (iriun.com) over WiFi or USB. We advise to lock the video stream orientation on your phone when using this setup to keep the stream aligned with the telescope's physical orientation.
  • 📷 Wide-Field Primary Camera Workaround: For setups using short focal length systems (e.g. William Optics RedCat, Askar FRA300/FMA180, SVBONY SV545/SV535, or short camera lenses), you can use your primary imaging camera directly as a webcam. If your camera supports DirectShow webcam drivers (common for ZWO, SVBONY, Player One, and ToupTek), simply disconnect the camera from N.I.N.A. temporarily. Horizon Studio will detect it as a local USB webcam, giving you a real-time stream with equatorial counter-rotation without needing a separate physical webcam setup.

---

🚀 Step-by-Step User Guide

1. Creating a New Horizon Profile

1. Connect your Mount and Camera in N.I.N.A., then open the Horizon Studio tab.
2. Align your camera crosshairs with your main telescope using the co-alignment helper.
3. Use the jogging controls to move the mount to the peak of a local obstacle (e.g. a tree top or roof line).
4. Click Drop Pin to save that horizon point.
5. Move the mount to the next obstacle along the horizon and click Drop Pin again. Repeat until you have mapped your sky.
6. Click Save Horizon Profile to save your .hrz file.

💡 Pro-Tip: The fastest way to build a profile is to map 3–4 macro "anchor points" around your sky first (e.g., major roof peaks or cardinal direction markers). Once those are dropped, click along the generated radar line to automatically slew nearby, and use the jogging controls to fine-tune the subtle dips and peaks.

---

2. Loading & Editing Profiles

• Load Profile: Click Load Horizon Profile to load a previously saved .hrz file.
• Add/Modify Pins: Slew to any area and click Drop Pin to add new nodes.
• Delete Pins: Click a node on the radar to select it, then click Delete Node to remove it.
• Verify Coords: Click ◀ Slew CCW or Slew CW ▶ to step through both your mapped nodes and landmarks by physical azimuth proximity, verifying that the telescope points clear of physical obstructions.

---

3. Auto-Set Active N.I.N.A. Horizon

When saving your horizon profile to a .hrz file, you can check the "Set as active N.I.N.A. horizon on save" checkbox located directly under the Profile Storage buttons.

• Instant Activation: When checked, saving your profile automatically updates N.I.N.A.'s active profile settings (Options > Astrometry > Horizon File) and triggers an instant reload of the horizon.
• No Restart Required: All active N.I.N.A. views, sky maps, and sequencer safety limits are refreshed in real-time immediately without requiring you to restart N.I.N.A.
• Persistent Preference: The state of this checkbox is saved and remembered across N.I.N.A. sessions.

---

4. Warp & Align Profiles (3D Tilt Correction)

The most common workflow is to build your horizon profile during the daytime — when you can clearly see trees, rooftops, and other obstructions — before your mount is polar-aligned. Once you perform polar alignment, the mount will inevitably shift, and your saved profile will no longer match the sky. 3D Tilt Correction allows you to warp and re-align the entire profile using a single reference point. It is also useful if the webcam co-alignment was skipped or done poorly, introducing a systematic offset into the profile, or if you have physically repositioned your mount since the profile was originally built. In either case, 3D Tilt Correction serves as a quick preliminary correction before fine-tuning individual nodes.

Horizon Studio supports three synchronization methods: Horizon Sync, Landmark Sync, and Polar Alignment Sync.

Method A: Horizon Sync (Using a Horizon Pin)

Use this if you want to align your profile using a physical feature that is already part of your horizon line (e.g., a specific chimney or post).

1. Select the pin on the radar that represents your physical landmark.
2. Click Slew in the active details card to move your telescope to it.
3. Click Prepare Sync.
   • The panel will enter Sync Mode, showing a pulsing purple highlight ring around the target node on the radar.
   • Jogging controls remain active, but pin drops and verification slews are locked for safety.
4. Look at your camera feed. Manually jog the mount until the physical landmark is centered under the crosshairs.
5. Once you jog the mount past the safety threshold ($0.05^\circ$), the Confirm Sync button becomes active.
6. Click Confirm Sync and approve the warping pop-up. The entire horizon line shifts and warps to match your mount's new alignment.

---

Method B: Landmark Sync (Using Terrestrial Landmarks)

Use this if you want to align your profile using one or more highly striking reference landmarks (like an antenna tip or tower peak) that sit above or below your actual horizon. Horizon Studio allows you to create and manage multiple landmarks. To prevent N.I.N.A. from treating them as obstructions, their coordinates are safely embedded as hidden metadata comment headers directly inside the .hrz file.

1. Adding Landmarks:

   • Slew your telescope and center a striking landmark under your camera crosshairs.
   • On the 🔷 SYNC LANDMARKS card, click ➕ Add. A new landmark will be created at your mount's current coordinates.
   • Repeat this for any other landmarks visible from your site.
   • (Optional) Click ✏️ Rename to give your landmarks custom names (e.g., "Antenna", "Tree").
   • Click Save Horizon Profile to store all landmarks directly in the file.

2. Calibrating in a Future Session:

   • Click Load Horizon Profile and load your .hrz file. All fuchsia diamonds (🔷) will immediately populate on both radars.
   • Select a landmark from the list or click its diamond on the radar. The active sync area will display the landmark's name and coordinates.
   • Click Slew to point your telescope at the landmark's saved position.
   • Click Prepare Sync.
   • Look at your camera feed and manually jog the mount to center the physical landmark under the crosshairs.
   • Once you jog the mount past the safety threshold ($0.05^\circ$), click Confirm Sync. The entire horizon profile (and all other landmarks in the collection) will shift and warp to match your new alignment!
   • Save your horizon profile to update the coordinates for all landmarks.

---

Method C: Polar Alignment Sync (Auto-Detect)

Use this if you have just completed polar alignment in your session and want to automatically align your horizon profile to the new coordinates without manual target syncing.

Important

When to use Polar Alignment Sync vs. Landmark/Horizon Sync:

• Use Polar Alignment Sync (Method C) only if you built or edited the horizon profile during the day, and then performed polar alignment at the exact same physical location without moving the tripod/mount (e.g. during a single, continuous session on the same physical footing). In this case, the coordinate shift is strictly the polar alignment error of the mount's axes, which the plugin can read from the logs and correct automatically.
• Do NOT use Method C if you are loading a saved horizon profile from a previous session where the mount/tripod has since been torn down, moved, or setup again (even slightly). Physical differences in tripod leveling and leg placement introduce complex shifts that log-based polar error cannot account for. In these cases, you must use Horizon Sync (Method A) or Landmark Sync (Method B) to calibrate the profile using a physical visual reference.

1. Complete a polar alignment run using N.I.N.A.'s Three Point Polar Alignment (TPPA) or 2-Point Polar Alignment (2PPA) plugins.
2. In Horizon Studio, load your horizon profile .hrz file.
3. Click the Auto-Detect Polar Offset button. The plugin will scan your recent N.I.N.A. log files (from the last 6 hours) to automatically retrieve the calculated Alt/Az alignment errors.
4. Click Apply Polar Sync.
5. Review the calculated correction coordinates in the confirmation pop-up.
6. Click Yes to warp the entire profile to match your new polar aligned coordinates.

---

3. Hardware & Safety Settings

This section of the control panel provides advanced mount integration and safety lockout limits to protect your equipment and improve slew/jogging precision.

Important

Safety Enforcement Behavior: All active safety blocks (Zenith Lock and Solar Safety) only apply to movements initiated inside the Horizon Studio plugin (such as clicking the radar canvas, manual jog buttons, active node slews, or landmark slews). Any telescope movements commanded outside the plugin (e.g., via N.I.N.A. sequence templates, the N.I.N.A. manual slew tab, or external applications like Stellarium) will not be interrupted or stopped by the plugin. The plugin's safety monitor will still display warning messages and turn on alert states in the UI to notify you of any proximity violations, but it will never issue a StopSlew() command or interfere with external operations.

• 🔄 EQ Auto-Rotate (Camera-Specific):
  • What it does: Automatically counter-rotates the visual overlay (Webcam or Main Camera) in real-time as the telescope tracks the sky.
  • Camera-Specific Routing: The state of the EQ Auto-Rotate checkbox dynamically routes and adapts to the active visual source. You can enable it for the webcam and disable it for the main camera, and it will toggle automatically when you switch feeds.
  • Why it is useful: For equatorial (EQ) mounts, the sky rotates relative to the horizon as the mount tracks. Auto-rotation ensures that the camera feed HUD overlays (the horizon profile and landmark diamonds) align perfectly with the target sky coordinates, regardless of the mount's hour angle or current tracking position.
• Rot. Angle:
  • What it does: Displays the calculated field rotation/parallactic angle in degrees.
• Offset Slider (Camera-Specific):
  • What it does: A manual adjustment slider (from -180° to +180°) to align the camera's physical orientation with the telescope's actual field alignment.
  • Camera-Specific Routing: Stored independently for each visual feed. The slider automatically updates and saves the offset corresponding to the active camera.
  • Why it is useful: If your webcam or main camera is mounted slightly tilted or rotated, this offset aligns the horizontal and vertical axes of the camera feed with the telescope's coordinate system.
• Solar Safety & The Sun Safety Region:
  • What it is: The Sun Safety Region is a dynamic $15.0^\circ$ exclusion zone around the Sun. The plugin calculates the Sun's position in real-time (once per second) based on your active N.I.N.A. profile's Latitude/Longitude and the PC's current UTC time.
  • What it does: When Solar Safety is enabled, it blocks any manual jog, radar slew, or landmark slew initiated inside the plugin that would point the telescope within $15.0^\circ$ of the Sun. It displays a red warning toast containing the correct bypass instructions (e.g. Disable 'Solar Safety' to bypass).
  • Why it is useful: Protects sensitive camera sensors and telescope optics from direct solar exposure and potential thermal damage during daytime mapping or alignment.
• Zenith Lock:
  • What it does: Prevents the plugin from executing any slew or jog to altitudes above $85.0^\circ$. If blocked, it displays a red warning toast with bypass instructions (e.g. Disable 'Zenith Lock' to bypass).
  • Why it is useful: Prevents physical mount collisions, cable wrap-around strain, or meridian/zenith tracking issues that can occur when pointing straight up.
• Horiz. Lock (Horizon Lock & Under-the-Pole Safety Floor):
  • What it does: Prevents the plugin from executing any manual jog, radar click slew, active node slew, or landmark slew that violates low-altitude safety thresholds:
    1. Polar Meridian / Under-the-Pole (UTP) Zone: If pointing near the polar meridian (within $\pm 20^\circ$ of North in the Northern hemisphere, or South in the Southern hemisphere), it enforces a safer altitude deck of $15.0^\circ$ to prevent the RA axis from wrapping $90^\circ$ into a software limit lockout.
    2. Standard Zone: If pointing outside the polar meridian zone, it enforces a standard safety floor of $0.0^\circ$ (exactly horizontal). If blocked, it displays a red warning toast containing the correct bypass instructions (e.g. Disable 'Horiz. Lock' to bypass).
  • Why it is useful: Acts as a physical safety floor to protect your telescope tube, camera train, filter wheel, and cabling from colliding with the mount pier or tripod legs, and prevents hitting firmware-level Under-the-Pole limits on German Equatorial Mounts (GEMs).
• 🎯 Exact Pos. (Exact Position):
  • What it does: Enables high-precision micro-step centering and drift compensation:
  1. During manual jogs, it bases the next jog target coordinates on the last requested coordinate target rather than the current reported position, preventing drift and lag creep when clicking multiple times in rapid succession.
  2. After slewing to a landmark, it measures the tracking lag/drift error, calculates a predicted lead, and automatically executes a small corrective micro-jump to center the target exactly.
• 📡 HUD Overlay (Radar Overlay):
  • What it does: Toggle switch to show or hide the augmented reality coordinate grid lines, landmark targets, and mapped horizon profile directly as an overlay on the live camera eyepiece view.

🛡️ Active Slew Travel Interception

When you command a slew or jog from within the plugin, the target coordinates are validated before the movement starts (IsTargetPositionSafe). In addition, the plugin registers this movement as an active plugin-initiated slew. During the slew, the 4Hz (250ms) background safety monitor actively checks the telescope's current live position (utilizing caching to restrict Keplerian Solar math calculations to once per second). If the telescope physically crosses into any active safety exclusion zone (such as sweeping directly through the Sun's $15.0^\circ$ Solar Safety Region or exceeding the $85.0^\circ$ Zenith Lock) during its travel, the plugin will immediately issue an emergency StopSlew() to abort the movement and protect your equipment.

This travel interception is strictly isolated to movements initiated from within the plugin, ensuring that standard N.I.N.A. sequence runs or external planetarium software slews are never interrupted.

⚠️ Large Diagonal Slew Confirmation

To prevent accidental large telescope movements, any plugin-initiated slews via manual jog buttons or radar clicks that exceed a combined $45.0^\circ$ diagonal displacement (calculated as $\sqrt{\Delta\text{Alt}^2 + \Delta\text{Az}^2}$) will prompt you with a safety confirmation dialog. This warning details the Alt/Az travel offsets, allowing you to safely abort the operation before the mount receives the command.

---

4. Exporting to Stellarium

Horizon Studio allows you to export your custom horizon profile directly into Stellarium as a polygonal landscape.

1. Map your horizon nodes as usual.
2. Click Save Horizon Profile.
3. Select Stellarium Landscape (*.ini) in the file type filter and save the file. By default, this will suggest a name like CustomHorizon_DATE_TIME_landscape.ini and automatically generate two files in your target folder: the main configuration file (e.g. CustomHorizon_DATE_TIME_landscape.ini) and the matching coordinate file (e.g. CustomHorizon_DATE_TIME_horizon.txt).
4. Install the saved files in Stellarium. Important: Stellarium requires the main configuration file inside its folder or ZIP archive to be named exactly landscape.ini. If you saved the configuration file under the default name (e.g., CustomHorizon_20260702_1943_landscape.ini), you must rename it to landscape.ini. The coordinate file (e.g., CustomHorizon_20260702_1943_horizon.txt) does not need to be renamed as it is automatically linked inside the INI.
   • Method A (Recommended - ZIP Import): This is the easiest method and does not require manually creating any folders.
     1. Rename your saved configuration file (e.g. CustomHorizon_20260702_1943_landscape.ini) to exactly landscape.ini.
     2. Select both landscape.ini and the matching coordinate file (e.g. CustomHorizon_20260702_1943_horizon.txt) and compress them together into a standard .zip archive (e.g., HorizonStudio.zip).
     3. Open Stellarium, press F4 to open the Sky and viewing options window, and go to the Landscape tab.
     4. Click Add/remove landscapes... at the bottom.
     5. Click Install a new landscape from a ZIP archive and select your HorizonStudio.zip file. Stellarium will automatically create all necessary directories and install the landscape.
   • Method B (Manual Install):
     1. Open the existing user configuration directory on your system:
        • Windows: Press Win + R, type %APPDATA%\Stellarium and press Enter.
        • macOS: Navigate to Library/Application Support/Stellarium in your user home folder.
        • Linux: Navigate to ~/.stellarium in your user home folder.
     2. Create a new folder named landscapes inside that directory (since it does not exist by default).
     3. Inside the landscapes folder, create a new subfolder named HorizonStudio.
     4. Copy both the coordinate file (e.g. CustomHorizon_20260702_1943_horizon.txt) and your saved configuration file into that HorizonStudio folder, ensuring the configuration file is renamed to exactly landscape.ini.
5. In Stellarium's Landscape tab (F4), select Horizon Studio Export from the list of available landscapes.

---

📝 License

This project is licensed under the MIT License.