Getting started

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 application has six tabs. The first tab loads at startup; the remaining tabs are created when first opened and then retained for the session. A first visit to a processing-heavy tab may therefore take slightly longer than returning to it.

1. Process Visual Obs.
2. Image Calibration & Stacking
3. Process CCD Obs.
4. Observation Planner
5. Light Curve Analyzer
6. Light Curve Comparison

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.

Next chapters

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