Help

Purpose

Occultation To NINA converts Discord-exported occultation TXT data into daily NINA sequence JSON files. It also builds planning tables with MPC, Gaia, JPL, Sun and Moon context for station X09.

This is Windows astronomy software in test mode. Inspect every generated NINA sequence before using it at the telescope. If something looks wrong, contact me; I will try to help, but support may take time.

Normal GUI Use

1. Put original single-day TXT files into the protected einzeln folder below the working folder. The folder is scanned on every run and those rows are preferred over imported extension rows.
2. Optionally add Discord HTML exports, copied discord.txt message text, or an extra selected TXT file with DATE yyyy-mm-dd or # yyyy-mm-dd lines.
3. Select the NINA source JSON to update it safely with the current observing night's occultation blocks. A baseline and a timestamp-preserving backup are written below the working folder. The former separate-file mode remains available on the CLI as --legacy-daily-json-output.
4. Check ROI X/Y plus ROI width/height. The GUI writes X/Y directly as the ROI corner expected by NINA.
5. Use Preview to check Wait For Time, capture end and frame count before running. The Defaults button restores the processing parameters.
6. Run the conversion. The selected NINA JSON is updated for the current observing night and copied to the Dropbox NINA-Occs folder if enabled.
7. The NINA JSON field is filled with the generated JSON for the current or next observing night. Use Open with N.I.N.A. to load that file.

Default Values

If Station contains a known MPC station code, the GUI fills latitude, longitude and height from the jostjahn.de station table and refreshes those values when the Station field changes. Unknown or invalid station codes clear the coordinate fields; invalid three-character codes are expected to use one letter followed by two digits. Manual edits are allowed for the current session, but they are overwritten on the next start while the station code is still known.

Input Format

Daily original TXT files belong in einzeln. They can be named yymmdd.txt; then the date comes from the filename. A selected TXT file with any name is accepted when it contains DATE yyyy-mm-dd or # yyyy-mm-dd before the event rows. Each useful table row contains name, RA, DEC, UT-Mitte, Duration, Exposure, Gain and ROI. Discord message text can also be converted; the website keeps the original discord.txt and generated daily TXT files for inspection.

If observation intervals overlap, original TXT rows are kept first. For rows with the same priority, the row with the brighter V Star value is kept when that value is available.

Discord message event times are audited against the supplied target altitude and Sun altitude. The default auto mode keeps the raw time as UTC when UTC fits better, but converts from America/Santiago to UTC when Chile local time is clearly the better match. The detailed result is written to discord_time_audit.csv.

NINA Output

Each event is written as an outer sequential container. The first item is Slew and Center with the event coordinates. The generated Lucky Target Container waits until capture start minus the configured video prep seconds, then runs Take Video Roi Exposures with the planned frame count. No loop-until condition is written. A Wait For Time at capture end is placed after the ROI video. The Take Video ROI exposure uses the planning table Real value rounded to 0.01 s and the frame count uses #. A normal full-frame 60 second exposure is added below the Lucky container to localize the field.

The working template's Loop and Dawn SunriseProvider conditions and offsets are preserved. The final Opp and its Search container also retain their original time providers and offsets, including dynamic Dawn rather than a replacement fixed clock time. Intermediate Opp blocks stop before the next event. Each occultation has an enclosing single-pass time window covering Slew and Center, the Lucky capture and the final 60-second localization image. Its deadline is capture end plus 60 seconds, capped at astronomical dawn; after that deadline, resetting the block in the same observing night cannot restart its slew. Labels include object, stellar V magnitude, occultation duration and probability; unavailable values are marked n-a, bounds use lt or gt, and labels avoid control and Windows filename-reserved characters. Time-only limits are not an expiry date: do not reuse a dated sequence on another night.

The input template is never overwritten. A separate current-night file is created in the output folder. Known older in-place files migrate from their hash-verified clean baseline; generated sequences are not accepted as new templates. The sequence name includes its observing night, UTC build time and event count.

Publication requires matching event counts, unique events and time providers, chronological night-bounded timing, a clean TimeCheck result and a successful NINA load test for the exact file bytes. Failure retains the previous public file. The automatic NINA test uses a temporary profile on a separate, invisible Windows desktop, never starts observations, and closes only its own test process. Software rendering allows an image check without activating that desktop. NINA must be installed; Tesseract OCR is used when custom controls do not expose their contents to UI Automation. Reports are stored in nina_load_test. Only a direct click on Open in N.I.N.A. starts a foreground window. An already loaded sequence does not update automatically: load the complete new sequence rather than adding it to the existing one.

The original Opp, Loop and Dawn conditions are preserved. TimeCheck reports are stored in nina_timecheck. The checked file is shown under TimeCheck for NINA and published at the configured stable URL, by default NINA-X09.json. Show next available night previews events from the working-folder input tables using the selected OCW setting.

Updates

The GUI checks update.json at most once per day. This request includes a random, stable UUID4 as installation_id; it contains no hardware, account, or personal data. When a newer version is available, the GUI offers the setup download and the website download page. If a known update is ignored for 60 days or more, the GUI stops running conversions until the update is installed.

Downloads And Installation

The recommended download is NinaOccultSetup.exe. The setup installs the GUI, CLI and this help page into the user profile and creates Start menu entries below amrumsoftware\NinaOccult. The portable GUI is available as a ZIP folder; the CLI EXE is for automation.