Getting started

Use canonical comet designations

Every comet input now uses one shared control. Enter an orbital designation such as 10P or C/2023 A3, not an unrestricted ordinary name. A value such as 10P/Tempel 2 is canonicalised to 10P; valid identifiers without local elements offer Add or update comet elements….

Open the Comet designation guide.

1. Start from the source root

Linux

cd /path/to/the/directory/that/contains/kopr.py
source .venv/bin/activate
python kopr.py

Native Windows PowerShell

cd C:\path\to\the\directory\that\contains\kopr.py
.\.venv\Scripts\Activate.ps1
python kopr.py

KOPR creates config-files/, comet-data/ and obs-data/ beside the program when they do not exist. The source root must therefore be writable.

2. Complete the first-start configuration

On a new installation, KOPR displays a configuration warning and reopens the Settings dialog until the required information exists.

Use the complete Configuration reference for field formats, save behaviour and instrument geometry.

3. Understand the main window

The current R144 application has five production tabs. The first tab loads at startup; the remaining tabs are created when first opened and retained for the session.

1. Process Visual Obs.
2. Image Calibration & Stacking
3. Process CCD Obs.
4. Observation Planner
5. Comet Analyzer

The former Analyzer and Comparison entry methods both route to the single Comet Analyzer tab.

4. Select the active observing context

Use the Configuration menus to select the Location, Telescope, Eyepiece and Camera used by the current workflow. The status bar shows the active context.

R56 preserves these four active selections in settings.dat and restores them at the next startup. KOPR no longer resets them to the first list entry merely because the application or Settings dialog was reopened.

R76: the active camera supplies explicit identity and native geometry, while the loaded observation supplies validated binning. Together with the active telescope they form the final optics fallback in the shared physical-scale chain; solved WCS/online calibration, manual override and FITS scale metadata take priority.

5. Choose the correct workflow

Recommended CCD image flow

This is an orientation map only. Detailed calibration, astrometry and stacking controls are assigned to the WStack chapter; measurement algorithms and result fields are assigned to the CCD chapter.

R79 reference-star flow: AutoStars and Manual Stars feed one canonical Reference stars collection. Review the user-enabled and pairwise-accepted states there, then use the same accepted IDs for Process obs. and Af-rho.

6. Allow first-run data updates

At startup KOPR checks central files and can update comet orbital elements when the local copy is missing or older than one day. Online star catalogues and other services are requested by the workflows that need them.

The first WStack astrometry request may install the local Astrometry.net 4206–4214 set. KOPR can also discover an optional 4100 family; its absence does not block the 4200 workflow. See Astrometry.net and local indexes.

7. Close KOPR safely

Use File › Exit, Ctrl+Q, or close the main window. KOPR asks loaded workflow tabs to stop their background workers before Qt destroys them. If an operation is still shutting down, KOPR may keep the window open and ask you to wait briefly and close it again.

First-session checklist

• KOPR starts from the directory containing kopr.py.
• The title bar shows the correct observer identity.
• The Configuration menu contains the expected saved items.
• The intended active rows are checked after opening or editing Settings.
• A camera is selected for WStack/CCD work and an eyepiece for visual work.
• A local astrometry backend is available: native solve-field, or on Windows a verified WSL installation.
• On Windows with multiple distributions, KOPR_WSL_DISTRIBUTION names the intended distribution exactly.
• The source root and selected image directory are writable.
• If the DE440s kernel is absent, complete the first-start download, choose Cancel to continue in legacy ephemeris mode, or use Retry after a failed attempt.
• For a release acceptance check, python3 validate_performance_release.py reports PASS.
• No manual thread-count or memory-limit setting is expected; R22 controls these values automatically.

Opening a DSLR RAW directory

1. Choose Open directory…. KOPR performs metadata-only discovery before changing the current WStack session.
2. If a CR2/CR3/NEF/ARW/DNG source lacks a valid current green representation, KOPR starts the dedicated extraction progress dialog immediately. No extraction question is shown.
3. The worker creates or refreshes linear TG FITS files beside their RAW sources and reports Extracted, Refreshed, Skipped and Failed counts. Cancel stops cooperatively between files.
4. After the batch, KOPR performs discovery again, verifies provenance and opens a FITS-only Raw page. It preselects a newly created/refreshed green FITS, or the first verified green representation when no batch was required.

See DSLR RAW → TG FITS materialization for conflict handling, state migration and cancellation details.

Optional WCCD helpers

When opening a New CCD/DSLR observation, you may enable Automatic comet finder, Auto star measure and the dependent online High-precision position — JPL Horizons. Accepted values are remembered as defaults for the next dialog; Cancel does not save them. Each successfully committed observation still receives independent one-observation helper state.

The observation and helpers start only after Accepted and successful preflight. Finder and Auto Stars report work in compact progress dialogs; the main WCCD image receives only the final validated Auto Stars catalogue markers and apertures.

The interactive finder searches to 120 arcsec around the expected position and always requires visual confirmation. Select a C1..Cn row or circle, or click the visible comet to create M1. Manual clicks, automatic candidates and M1 use the same bounded 2D Gaussian comet-centroid model. A valid review cutout remains usable even if no automatic candidate survives.

Confirming a centre changes only the centre; the accepted coordinates then become authoritative for the WCCD marker, Slice geometry, comet aperture measurement and ACF. The unattended complete automatic-photometry path retains its stricter 30-arcsec gate.

Auto Star Measure uses the same pipeline in ordinary and crowded fields. Its R55 report distinguishes raw and robust FWHM, shows whether the common aperture came from a plateau or the robust-PSF fallback, and reports post-aperture blend rejection and the background method. Moderate elongation, aperture fallback, 3–7 final stars, heavy clipping or scatter up to 0.15 mag are warnings; fewer than three final stars, a non-finite aperture pixel or scatter above 0.15 mag are hard failures.

The measurement selector also provides Slice Through Comet and Slice Between Points for raw one-pixel image profiles in an independent non-modal window. See Automatic helpers and Slice profiles.

R80–R81 operator notes

• In Reference stars, the Use checkbox represents effective inclusion after quality and pairwise evaluation. Read Reason for an unchecked star; there is no separate Pairwise status column.
• Reopening a DSLR directory must not report CO/ST, calibrated or WCS derivatives as competing direct RAW representations. Direct green FITS uses RAWREP=T; downstream products are marked derived or stripped of direct-representation cards.
• Repeating comet, star or tail measurement preserves zoom and pan when the required image role is already active. A necessary Comet/Stars role switch still redraws once.

R93 ephemeris and WCCD operator notes

1. Check the local model: from the KOPR directory run python3 check_nbody_status.py. An available runtime reports model: nbody, Status: activated and Reason: automatic_runtime_available.
2. Read provenance, not offsets: during a calculation, inspect the terminal line containing requested, used, source, cache action and any fallback reason. Automatic Comet Finder also labels the internal engine in its confirmation window.
3. Open one-stack WCCD observations: choose the Comet stack first. Leave Stars empty, or choose the same FITS, to create a full Stars logical role from the Comet product without duplicate file I/O.
4. Use the new dialog order: Comet stack, optional Stars stack, then canonical Comet designation. FITS OBJECT may populate the designation until the user edits it manually.
5. After 100% finder progress: the progress window is hidden before the candidate review is built in the main Qt thread. A stale result from an older observation remains rejected.

Which ephemeris model each tool uses

KOPR R121 uses task-specific profiles rather than one expensive model everywhere.

Historical Analyzer/Comparison client names normalize to the same WLIGHTCURVES_POLICY; they are not separate modes.

The profile is fixed by the widget and is not a user-selectable quality setting. See Performance and platform limits for scheduling and cache details.

Next chapters

Configuration · Image Calibration & Stacking · Process CCD Obs. · Troubleshooting