Getting started

Other capture software

Not yet released. The standalone uploader is built and tested but has no installer, signature or download yet, and the service itself is still in its pilot. The download page shows its current state. These notes describe what it does so you know what to expect.

If you capture with something other than N.I.N.A. (SGP, Voyager, APT, Ekos/KStars, an ASIAIR, or just a folder of files from anywhere), the standalone uploader does what the N.I.N.A. plugin does: it signs in, joins a project, and uploads your frames, from a terminal. It is called collab-uploader. It is one small program with no other software to install.

What it does

  • Signs in without a password, like the plugin: it shows a code, and you approve it on the approval page while signed in here.
  • Joins a project with its join code. It shows the rules and the terms of contribution first and joins nothing until you say you accept them.
  • Suggests your filter mapping from the filter names in your own files, with the same suggestions the plugin and the site give. See filter mapping.
  • Uploads files or folders, or watches a folder and uploads new frames when they are finished being written. A queue on disk survives restarts, and a half-sent frame resumes where it stopped.
  • Can share your connection: --bandwidth-limit "2 MB/s" (or "8 Mbit/s"; a unit is always required) caps the upload speed across all the parts it sends at once.
  • Uploads only when you want: --upload-window 06:00-14:00 (local time; 22:00-06:00 crosses midnight) keeps queueing frames at any hour but sends them only inside the window. upload outside it queues and stops unless you add --now.
  • Sends only what the project can use: light frames (calibration frames if you ask), of the right target, with an exposure and a camera type the project accepts. It tells you why it left a file out.

Your location is removed, and your files are not touched

Before anything is sent, the uploader makes a temporary copy of each file without SITELAT, SITELONG, SITEELEV, OBSERVER and the other names capture software uses for them, and without horizon coordinates such as altitude and azimuth, which would give your position away just as well. It checks the copy, uploads the copy, and deletes it. This cannot be switched off. Your original files are opened for reading only: not changed, not renamed, not moved. FITS and XISF are both handled. See privacy.

The steps

  1. Register here and get a join code from the project owner, as in how to join a project.
  2. Sign in: collab-uploader login. Open the address it prints, check that the code matches, approve.
  3. Join, with a folder of your own frames so it can read your filter names: collab-uploader join CODE --from FOLDER. Read what it shows. Then run it again with --accept-terms. A filter name it cannot place needs --map "NAME=FILTER", or --map "NAME=SKIP" to never upload it.
  4. Confirm your camera and telescope from one of your frames: collab-uploader rig confirm --from FILE.
  5. Upload what you have: collab-uploader upload FOLDER. Or leave it running while you image: collab-uploader watch FOLDER.
  6. See what became of your frames: collab-uploader queue --refresh, or your dashboard. What each reason means.

Which project a frame goes to

A light frame goes to the project whose target name matches the frame's OBJECT, or whose project frame contains the position the frame was pointed at. If more than one matches, or none does, the uploader skips the file and says so; --project sends everything to one project instead. Calibration frames (--include-calibration) go to your only project, or to the one you name.

Watching a folder

Capture software often writes to a network share, so the uploader looks at the folder every few seconds instead of waiting to be told. A file is picked up once its size and time have stopped changing for a while (10 seconds by default), so a frame that is still being saved is left alone. Stop it and start it again whenever you like: it remembers what it has already sent.

If something goes wrong

  • A quota is used up (the project's limit on your uploads): it pauses that project, keeps the files, and checks again later.
  • The service is busy or paused: it waits as long as the service asks, then carries on.
  • A frame breaks a project rule (too short an exposure, a colour camera in a mono project): that file is marked failed with the reason; the others go on.
  • Your sign-in has expired (they last 180 days) or you revoked it: it stops, keeps everything queued, and asks you to sign in again.
  • The connection drops: it retries on its own and resumes the same frame.

The full list is in the uploader's own documentation, docs/runbooks/uploader.md in the project repository.

What it does not do yet

There is no tray icon, installer or automatic update yet, only the plugin's daily time window as an upload schedule (not "when idle" or "after the sequence ends"), and your token is kept in a file only you can read rather than in the system keychain. For a handful of frames from any computer, the browser uploader, on a project's upload page, needs nothing installed.