Installation

How KOPR is distributed and started

KOPR is distributed as Python 3 source code. Extract the complete archive, install its dependencies in a Python environment and start the application from the directory containing kopr.py. Do not mix files from different releases; replace the complete KOPR source tree when upgrading across releases.

Supported installation model

KOPR supports both a source checkout and an installed Python package. In a source checkout use python3 kopr.py; an installed package uses the kopr CLI. Both routes enter the same canonical application owner. On Windows, WSL 2 remains only an optional backend for the external Astrometry.net solve-field command; the KOPR GUI, FITS files, working directories and local index library remain on the Windows side.

KOPR first prefers a native solve-field executable on PATH. When KOPR is running as a native Windows Python process and no native solver is available, it probes the default WSL distribution. A non-default distribution can be selected with KOPR_WSL_DISTRIBUTION.

Requirements

KOPR requires a readable DE440s kernel for the authoritative N-body route. A kernel path being present is not sufficient by itself: runtime readiness also requires jplephem and SciPy. Startup diagnostics distinguish missing/unreadable kernel from missing dependencies.

Optional JPL support can be added inside the same virtual environment:

python -m pip install astroquery

Do not make astroquery a hard runtime requirement when offline WCCD operation is sufficient.

Internal N-body ephemeris runtime

jplephem is an explicit runtime dependency. Planner performs its N-body runtime preflight before Phase A, so a missing dependency fails early rather than starting hundreds of search jobs. The error identifies the discovered kernel path and the missing component.

python3 -m pip install jplephem
python3 check_nbody_status.py

Expected healthy application selection: KOPR application ephemeris model: nbody with reason automatic_runtime_available. A failed readiness check is not permanently cached; after installing a missing dependency you can retry in the same session.

Ubuntu/Linux installation

1. Install operating-system packages

   sudo apt update
   sudo apt install python3 python3-venv python3-pip unzip astrometry.net

   The Ubuntu astrometry.net package supplies the solve-field command. KOPR manages its own application-local index set separately.

2. Extract the complete source archive

   Keep the directory structure intact. In the example below, replace the archive name and extracted directory name with the actual names.

   mkdir -p ~/kopr
   cd ~/kopr
   unzip ~/Downloads/kopr-live-python3.zip
   cd path/to/the/directory/that/contains/kopr.py

   Confirm the working directory:

   test -f kopr.py && echo "KOPR source root found"

3. Create an isolated Python environment

   python3 -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip

   A virtual environment avoids the externally-managed-environment/PEP 668 error produced when pip is used against the operating-system Python.

4. Install the Python dependencies

   Download the KOPR requirements list into the source root, then run:

   python -m pip install -r kopr-python-requirements.txt

   Equivalent direct command:

   python -m pip install PyQt5 matplotlib numpy astropy requests jplephem ExifRead rawpy scipy urllib3

   rawpy provides the LibRaw backend required for automatic DSLR RAW → TG FITS materialization. When pending or stale RAW representations are found without this dependency, KOPR reports DSLR RAW extraction unavailable; existing FITS may still open, but physical RAW is never loaded directly.

5. Verify the installation

   python --version
   command -v solve-field
   python -c "import PyQt5, numpy, scipy, astropy, matplotlib, requests, jplephem, exifread, rawpy; print('Python dependencies OK')"

   You can also download the non-destructive installation checker into the source root and run:

   python check-kopr-install.py .

6. Start KOPR

   source .venv/bin/activate
   python kopr.py

Astrometry.net and local indexes

Two separate components are required:

1. The solver: the external solve-field program.
2. The index files: local FITS data files used by the solver.

WStack resolves a usable solver backend before it checks or downloads the large index library:

1. use native solve-field when it is on PATH;
2. on native Windows, otherwise probe solve-field in the selected WSL distribution;
3. only after solver preflight succeeds, discover local 4100/4200 families and install the established 4206–4214 set when it is missing.

The application-local indexes remain in the KOPR directory on both Linux and Windows:

astrometry-index/4100/   # optional Tycho-2 family
astrometry-index/4200/   # established automatic-download family

KOPR reports the available families and wide-field recommendation in [INDEX] terminal lines. Missing 4100 indexes produce a warning only; they do not block a valid 4200 installation. Automatic downloading still installs 4206–4214.

The downloader preserves partial files after cancellation and resumes them later. Keep sufficient free disk space and make the KOPR source directory writable. Do not create an empty completion marker manually; readiness is checked against the actual index FITS files.

Native Windows installation with the WSL Astrometry.net backend

KOPR itself runs as a normal Windows Python application. Ubuntu does not need to be opened for each observing session; WSL is started automatically when astrometry calls solve-field.

1. Install KOPR and Python on Windows

   Extract the complete KOPR archive to a writable directory on a local disk, for example C:\KOPR. Install a supported 64-bit Python 3.10 or newer and create a virtual environment in PowerShell:

   cd C:\KOPR
   py -3 -m venv .venv
   .\.venv\Scripts\Activate.ps1
   python -m pip install --upgrade pip
   python -m pip install -r docs\files\kopr-python-requirements.txt

   If PowerShell blocks activation, use Set-ExecutionPolicy -Scope Process Bypass for that terminal session or activate from cmd.exe with .venv\Scripts\activate.bat.

2. Install WSL 2 and Ubuntu

   Open PowerShell as Administrator:

   wsl --install -d Ubuntu

   Restart Windows when requested. If normal download fails, use:

   wsl --install --web-download -d Ubuntu

3. Initialize Ubuntu once

   Open Ubuntu from the Start menu and create the Linux username and password requested during first initialization. Characters are not displayed while typing the password.

4. Install Astrometry.net inside Ubuntu

   sudo apt update
   sudo apt install -y astrometry.net

   If the package is not found:

   sudo apt install -y software-properties-common
   sudo add-apt-repository universe
   sudo apt update
   sudo apt install -y astrometry.net

5. Verify the solver in Ubuntu

   command -v solve-field
   solve-field --help

   The command path is normally /usr/bin/solve-field.

6. Verify the solver from Windows

   Close Ubuntu and run in ordinary PowerShell:

   wsl.exe -d Ubuntu -- sh -lc "command -v solve-field"
   wsl.exe -d Ubuntu -- sh -lc "command -v solve-field >/dev/null && solve-field --help >/dev/null && echo ASTROMETRY_OK"

   The second command should print ASTROMETRY_OK.

7. Confirm WSL 2

   wsl --list --verbose

   The selected distribution must show version 2. Convert an older installation with:

   wsl --set-version Ubuntu 2

8. Select a non-default distribution when necessary

   The current implementation probes the default WSL distribution unless an explicit override is supplied. For the current PowerShell session:

   $env:KOPR_WSL_DISTRIBUTION = "Ubuntu-24.04"

   Use the exact name shown by wsl --list --verbose. KOPR does not automatically iterate through every installed distribution.

9. Start KOPR natively

   cd C:\KOPR
   .\.venv\Scripts\Activate.ps1
   python kopr.py

   At astrometry start, KOPR first looks for a native solver and then uses WSL if necessary. Windows paths are translated with wslpath; resulting WCS files are written back into the original Windows working directory.

Updating a live source installation

1. Close KOPR and wait for any WStack worker to finish.
2. Back up config-files/, comet-data/ and obs-data/.
3. Extract the new live archive into a new directory rather than overwriting a running installation blindly.
4. Create or reuse a virtual environment and install the requirements.
5. Copy your backed-up user-data directories into the new source root.
6. Run the installation checker, then start KOPR.

WStack session state is stored with each working directory in pipeline_state.json; it is not part of the central KOPR configuration backup.

Installation diagnostics

Run check-kopr-install.py. On native Windows it accepts either a native solver or a verified WSL solver backend.

Continue with Getting started after the required checks pass.

External references

• Python documentation: virtual environments
• Microsoft: install WSL
• Microsoft: basic WSL commands
• Astrometry.net code and index overview

Planner local star catalogues

Current fixed roots are ./koprtyc2 for TYC2 and ./koprybsc5 for Yale BSC5. Missing or damaged catalogues use the explicit Download local / Use online / Cancel workflow; validated downloads publish atomically.

Upgrade safety

Apply an incremental DIFF only to the exact immediate baseline named for that DIFF. If a release was skipped or the installed state is uncertain, replace the complete kopr/ tree with the full Production ZIP. KOPR rejects mixed-version finding-chart components before map generation.