Command Line Interface

All commands share the same syntax:

imo-vmdb <command> [options]

The database is configured either via a config file (-c config.ini) or via environment variables. See Setup for configuration details.

initdb

Initializes the database schema:

imo-vmdb initdb -c config.ini

Warning

Running initdb on an existing database will delete all data in it.

import_csv

Imports one or more CSV files into the database. The import is the first of two stages — see normalize for the second stage.

During import, every record is checked individually. Records that fail validation are rejected with an error; records that look suspicious but are still acceptable trigger a warning. For the expected column names and format of each file type, see CSV files.

Example — import all 2020 files:

imo-vmdb import_csv -c config.ini data/*-2020.csv

Available options:

• -d — delete previously imported data before importing

• -p — permissive mode (see below)

• -r — repair mode (see below)

The -d option is useful when you want to re-import a single file without running cleanup first.

Permissive mode (-p) accepts records that would normally be rejected, logging a warning instead of an error. The following cases are affected:

• Observation periods where start time equals end time.

• Sessions with no elevation value (normally a required field).

• Rate observations with a teff (effective observing time) greater than 7 hours, up to a maximum of 24 hours.

• Magnitude records where the running magnitude-count sum has a fractional remainder at an intermediate step. The final total across all magnitude classes must still be a whole number in all cases.

Repair mode (-r) attempts to automatically correct certain malformed values before validation. A warning is logged for every correction applied. The following corrections are attempted:

• Sentinel values in declination — values 990 and 999 are treated as missing rather than causing a rejection.

• Sentinel value in right ascension — a value of 999 is treated as missing.

• Asymmetric RA/Dec pair — if only one of right ascension or declination is set, both are cleared to missing.

• Inverted observation period — if the end time precedes the start time, the two are swapped, provided the resulting duration does not exceed 0.49 days (~11 h 46 min).

• Off-by-one-day error — if the observation period is invalid but becomes valid by shifting the end date one day forward or backward, that correction is applied (subject to the same maximum duration).

Both options can be combined.

normalize

Normalizes the imported records and enriches observations with computed astronomical data:

imo-vmdb normalize -c config.ini

The following data are computed and stored:

• solar longitude,

• position of the radiants,

• position of the sun,

• position of the moon and its illumination,

• position of the field of view,

• radiant altitude with zenith attraction applied.

All positional data are in the horizontal coordinate system.

Further plausibility checks are applied during normalization:

• observations where the sun is above the horizon are rejected,

• overlapping observations within the same session are discarded as duplicates.

Warning

Re-normalizing a session deletes all existing records for that session and recreates them from scratch.

After normalization is complete, the raw imported records can be removed with cleanup.

cleanup

Removes raw imported data from the database while preserving all normalized results:

imo-vmdb cleanup -c config.ini

web_server

Starts the web server, which always serves the REST API at /api/v1. The browser-based control panel (Web UI) is opt-in:

imo-vmdb web_server -c config.ini                  # REST API only
imo-vmdb web_server -c config.ini --enable-webui   # REST API + Web UI

For a quick start without a config file, pass the database path as an environment variable:

IMO_VMDB_DATABASE_DATABASE=./data/vmdb.db imo-vmdb web_server --enable-webui

The server listens on http://127.0.0.1:8000 by default.

Additional options:

• --host HOST — network interface to bind to (default: 127.0.0.1, also configurable via IMO_VMDB_WEBSERVER_HOST)

• --port PORT — port number (default: 8000, also configurable via IMO_VMDB_WEBSERVER_PORT)

• --enable-webui — also serve the browser-based control panel at / (also configurable via IMO_VMDB_WEBSERVER_ENABLE_WEBUI=true)

To make the server reachable from other machines on the network:

imo-vmdb web_server -c config.ini --host 0.0.0.0

Note

The web server is intended for local or trusted-network use only. It is not hardened for public internet exposure.

When the server starts, Flask prints the following message:

WARNING: This is a development server. Do not use it in a production
deployment. Use a production WSGI server instead.

This is expected behaviour. The warning refers to deployments on a public server; it does not apply to local use on your own computer. You can safely ignore it.

See Web UI for a description of the interface.

export

Exports a single table as a semicolon-delimited CSV file or the entire database as a SQLite file:

imo-vmdb export <target> [-c config.ini] [-o output_file]

Available CSV targets (one table per call):

Target	Description
shower	Meteor shower data from the database
radiant	Radiant position data from the database
session	Observation sessions
rate	Normalised rate observations
magnitude	Normalised magnitude observations
magnitude_detail	Per-magnitude-class frequency counts
rate_magnitude	Rate-to-magnitude cross-reference

For CSV targets, output goes to stdout when -o is omitted.

The --reimport flag is available for shower and radiant. It exports the original embedded reference files in the exact format required for re-import with import_csv:

imo-vmdb export shower --reimport -o showers_edited.csv

Without --reimport, all CSV targets — including shower and radiant — are exported directly from the database using the field names documented in Field Reference.

Exporting the whole database

The special target db writes the entire database (normalized observations and reference data, but not the raw imported_* tables) into a single SQLite file:

imo-vmdb export db -o snapshot.sqlite

The resulting file uses the same schema as a regular imo-vmdb database. The recipient can use it directly as their own imo-vmdb database.

When db is the target, -o is required and --reimport is not supported.