Rejects and Database Sync

Move rejected frames out of the folders your stacking tool reads, remove old rejects from the catalog, and copy captures, plans and grades between two catalogs: two database files, or two PSF Guard servers.

Archive rejected files

Stacking tools such as PixInsight load every file under your lights folder, rejected frames included. move-rejects moves each rejected frame and its sidecars (.json and .txt by default) into a REJECT/ folder just below the project folder, and records where each came from:

# Move rejects to <image_dir>/<Project>/REJECT/... with their sidecars.
# Re-runs skip frames already moved.
psf-guard move-rejects --db my-db --dry-run
psf-guard move-rejects --db my-db

# Un-reject frames in the UI, then bring them back
psf-guard restore-rejects --db my-db          # only frames no longer Rejected
psf-guard restore-rejects --db my-db --all    # everything in the archive

• Recorded. Each move is saved in a psf_guard_archive table in the database, with a manifest file in each archive root for recovery.
• Reversible. restore-rejects brings back frames no longer graded Rejected; --all brings back everything, and --image-id or --guid one frame. It never overwrites: a file whose original path is taken comes back with a .restored suffix.
• Calibrated copies move too. A rejected frame's calibrated and registered copies, such as WBPP's, move into the archive beside their own folders and come back on restore. A copy that cannot be found, or would overwrite something, is listed and left where it is.
• Still searchable. Archived frames stay indexed in the grader, since the index covers the REJECT/ folders.
• Configurable. --reject-segment (default REJECT), --reject-depth (default 1) and --sidecar-exts change the layout, as does a reject_archive block on the database's registry entry. A FITS or XISF file is never taken as a sidecar: it has its own grade.

Remove old rejects

An archived reject stays in the catalog. To take frames that are truly bad out of it, and free their disk space, remove them. Removal runs only when you ask, and a restore undoes it until the trash is emptied. It needs an editor.

1. In Settings → Databases, click Purge Rejects beside the database's Import.
2. Choose how many days a frame must have been rejected (7 by default; 0 takes every reject) and click Preview. The preview lists the frames and their size, and explains why any rejected frame will remain.
3. Choose how many days to keep the files in the trash (14 by default) and click Remove N frames.

• Dated. PSF Guard dates each reject when it first sees it. A frame no longer rejected loses its date, so rejecting it again starts the wait over.
• Trash. Each frame's file, and its calibrated and registered copies, move to a .psf-guard-trash folder in its image directory, never overwriting. The frame leaves the catalog and its cached previews and scans are deleted.
• Kept. Frames a collaboration report lists, and frames whose file another frame also uses, stay.
• Restore on a removed batch puts its files and rows back. A taken file name comes back with a .restored suffix.
• Empty trash appears once a batch is past its time in the trash, and deletes those files. Nothing deletes them on its own.
• Purge appears once a batch's files are gone, and forgets its saved rows. A marker for each frame stays.

Sync pulls, imports, automatic imports and remote uploads leave removed frames out, purged ones included, and plan progress still counts them as rejected. Removal changes only this catalog: a rig's own Target Scheduler copy keeps its rows.

# Preview, then remove frames rejected 7 days ago or more.
# --cache-dir points to the server's cache, so the frames' cached files go too.
psf-guard remove-rejects --db my-db --days 7
psf-guard remove-rejects --db my-db --days 7 --apply --cache-dir /path/to/cache

psf-guard list-removed --db my-db
psf-guard restore-removed --db my-db --batch <batch>
psf-guard empty-reject-trash --db my-db    # files past their time in the trash
psf-guard purge-removed --db my-db         # saved rows of emptied batches

Direct database access (deprecated)

Your current Target Scheduler setup will keep working in 0.12, including direct CLI/API access. A later update will create a PSF Guard catalog for you and keep captures, plans and grades in sync with Target Scheduler. Separate catalogs let us add features to PSF Guard and support new Target Scheduler versions. We plan to remove direct database access in 0.13 or later.

For new Target Scheduler databases, choose Settings → Databases → Import from Target Scheduler to import the database and set up sync.

Import a local TS file and keep the source connected, or choose the N.I.N.A. Sync plugin for a network connection.

Image folders can be read-only. A directly opened database must be writable to save grades and plans. When both applications use that file, those edits need no transfer. New imports use a separate working catalog instead.

Sync two database files

Grade on one machine while the telescope keeps capturing on another. Sync copies chosen state between two Target Scheduler databases, each given as a registry slug or .sqlite path, and matches rows by their stable GUID (schema 22 or later).

Data Transfer in Settings

For an imported TS catalog, the saved Target Scheduler connection appears beside the owned catalog in the source and destination lists. You do not need to register the source as a second catalog. Turn off automatic grade writeback if you want to send grades only after review.

Open Settings → Sync. Data Transfer takes a Source and a Destination and offers three directions:

Each direction makes a preview on the server first. The preview keeps a frozen copy of the source and comes back after a page reload. Apply refuses if the destination changed since the preview. The Sync tab needs an editor.

Calibration travels with a merge

Merge catalogs and sync pull also copy the calibration library: rigs, raw calibration-frame records and their grades. Generated masters and cached files stay behind; the destination builds its own. With them travel the choices that change which frames a master takes or which flats PSF Guard uses for a light:

• Keep out and Use anyway on calibration frames. When both catalogs hold a choice for a frame, the later one wins. A choice made on the destination stays with its file when the source catalogued that file under another ID.
• Flat groups split or joined by hand, and lights put on a side of a change or given one group's flats, matched by flat and light GUID. The later choice or reset wins.

The preview counts these choices, such as "Calibration choices: 3 kept out, 1 used anyway. Masters built from these frames change.", because they change the destination's masters. The Remote PSF Guard preview counts them as calibration choices.

An import catalogues a calibration frame that is on disk twice, such as a copy a filer has not yet cleaned out of the drop folder, once; when the original goes, its row moves to the copy and keeps its grade and marks. A later pull does not undo a duplicate repair: a row a repair merged here is never brought back from a catalog that still holds it, and a row the source's repair merged is merged here too, its masters built again. The source keeps its own duplicates until it is repaired there. See Calibration Libraries.

Sync from the command line

# Captures and structure FROM the telescope INTO your copy.
# Your reviewed grades stay; new frames arrive with the telescope's grade.
psf-guard sync pull --from telescope.sqlite --to my-db --dry-run

# Edited projects, targets, templates, plans and rule weights back TO the telescope.
# Its captures, counts and grades stay.
psf-guard sync planning --from my-db --to telescope.sqlite --dry-run

# Your grading decisions back TO the telescope (one way, source wins).
psf-guard sync grades --from my-db --to telescope.sqlite --dry-run

• sync pull copies projects, targets, templates, exposure plans, rule weights and captured images, and the calibration library with its choices, as above. The telescope wins for structure. An existing frame keeps its local grade unless that is Pending, in which case it takes the telescope's. --no-image-data skips the thumbnails.
• sync planning copies project and target settings, templates, exposure plans and rule weights. It never touches capture history, frames or grades. New plans start with no frames taken.
• sync grades copies grades and reject reasons. --status, --project and --target narrow what it sends.

All three open the source read-only, refuse when source and destination are the same file, run in one transaction, and report matched, changed, unchanged and unmatched rows. Each takes --dry-run and --project.

How rows match

Staged previews

Settings → Sync → Staged previews lists every transfer waiting on the server, including those the N.I.N.A. plugin sent: the catalog, operation, source, change counts and expiry. Expand What would change for the field changes, grade transitions, reject reasons, and the projects, targets, plans or frames to be inserted or updated, up to 400 lines.

• Apply writes the reviewed changes to the destination.
• Refresh compares the saved source with the destination again, after the destination changed.
• Discard deletes the preview and changes nothing.

Nothing changes until you click Apply. The server prepares large previews in the background while the page checks progress.

In Data Transfer and Remote PSF Guard, you can change options while a preview runs. PSF Guard stops that preview; click Preview changes to check the new choices. A newer preview replaces one still running. You can also stop previews from the header’s jobs list.

Sync with another PSF Guard

One PSF Guard can sync with another over HTTP: no shared file system, and no copying a live SQLite file. The peer must allow it. On the peer, edit the catalog under Settings → Databases, generate a Remote API key, and tick Accept remote scheduler sync. A server with no Settings grants the same with a [[remote_sync]] block in its config file; see Configuration.

Then, on this server, open Settings → Sync → Remote PSF Guard:

1. Click Add peer, enter its Name, Base URL and API key, and click Save peer. The key stays on the server and is never sent back to the page.
2. Click Test connection.
3. Choose Pull from peer, Send planning or Send grades, and the Local catalog.
4. Click Preview changes, read the counts, then Apply this preview.

The command line does the same, for a terminal or a cron job:

psf-guard sync remote --direction pull \
  --local review --peer https://telescope.example:3000 --token-file key.txt

--direction takes pull, push-planning or push-grades. Every direction previews first. A push is reviewed by the peer, which writes nothing until the preview it issued is applied. --dry-run stops after the preview. push-grades sends only reviewed grades unless you pass --all-grades. The key comes from --token-file, then PSF_GUARD_SYNC_TOKEN, then --token; an argument is visible to every process on the machine.

The peer appends every remote action, refusals included, to remote-sync-audit.jsonl in its cache folder.

Run the whole loop

# 1. Bring the night's captures over from the telescope
psf-guard sync pull --from telescope.sqlite --to my-db

# 2. Screen the night and write supported rejections
psf-guard screen-fits /images/2026-06-30/LIGHT --regrade-db my-db

# 3. Review borderline frames in the grader
psf-guard server

# 4. Archive rejects out of the stacking tree
psf-guard move-rejects --db my-db

# 5. Send plans and final grades back so the scheduler re-captures
psf-guard sync planning --from my-db --to telescope.sqlite
psf-guard sync grades --from my-db --to telescope.sqlite