17 KiB
CCD/CMOS imaging server
Supports FLI cameras/focusers/wheels and cameras: ZWO, Basler, HikRobot, PointGrey, Apogee, ToupCam. Allows to run as standalone application or imaging server/client.
To restart server (e.g. if hardware was off) kill it with SIGUSR1 or send command restartTheServer.
Compile
The tool itself depends on usefull_macros librariy. "Artifical star" plugin depends on my improclib. The image viewer depends on OpenGL and GLUT libraries (also depending on X11). All other plugins (excluding "dummy camera") depends on third-party libraries. The Apogee plugin also depends on apogee C wrapper.
I will try later to combine all third-party libraries in this repository.
cmake options:
-DAPOGEE=ON- compile Apogee plugin-DASTAR=ON- compile "artifical star" plugin-DBASLER=ON- compile Basler support plugin-DDEBUG=ON- make with a lot debugging info-DDUMMY=OFF- compile without dummy camera plugin-DEXAMPLES=ON- compile also some exaples of libccdcapture use-DFLI=ON- compile FLI support plugin-DFLYCAP=ON- compile GrassHopper PointGrey plugin-DHIKROBOT=ON- compile HikRobot support plugin-DIMAGEVIEW=OFF- compile without image viewer support (OpenGL!!!)-DTOUPCAM=ON- compile ToupCam support plugin-DZWO=ON- compile ZWO support plugin
Usage
Usage: ccd_capture [args] [output file prefix]
Args are:
-0, --timeout=arg network answer timeout (default: 0.1s)
-8, --8bit run in 8-bit mode
-A, --author=arg program author
-C, --cameradev=arg camera device plugin (e.g. devfli.so)
-D, --display Display image in OpenGL window
-F, --focuserdev=arg focuser device plugin (e.g. devzwo.so)
-I, --instrument=arg instrument name
-L, --list list connected devices
-N, --obsname=arg observers' names
-O, --object=arg object name
-P, --prog-id=arg observing program name
-V, --verbose verbose level (-V - main messages, -VV - secondary messages, -VVV - debug)
-W, --wheeldev=arg wheel device plugin (e.g. devdummy.so)
-Y, --objtype=arg object type (neon, object, flat etc)
-_, --plugincmd=arg custom camera device plugin command (can occur multiple times)
-a, --addsteps=arg move focuser to relative position, mm (only for standalone)
-c, --conf-ioport=arg configure I/O port pins to given value (decimal number, pin1 is LSB, 1 == output, 0 == input)
-d, --dark not open shutter, when exposing ("dark frames")
-f, --fast fast readout mode
-g, --goto=arg move focuser to absolute position, mm
-h, --hbin=arg horizontal binning to N pixels
-i, --get-ioport get value of I/O port pins
-k, --shmkey=arg shared memory (with image data) key (default: 7777777)
-l, --nflushes=arg N flushes before exposing (default: 1)
-n, --nframes=arg make series of N frames
-o, --outfile=arg output file name
-p, --pause=arg make pause for N seconds between expositions
-r, --addrec=arg add records to header from given file[s] (can occur multiple times)
-s, --set-ioport=arg set I/O port pins to given value (decimal number, pin1 is LSB)
-t, --set-temp=arg set CCD temperature to given value (degr C)
-v, --vbin=arg vertical binning to N pixels
-w, --wheel-set=arg set wheel position
-x, --exptime=arg set exposure time to given value (seconds!)
--X0=arg absolute (not divided by binning!) frame X0 coordinate (-1 - all with overscan)
--X1=arg absolute frame X1 coordinate (-1 - all with overscan)
--Y0=arg absolute frame Y0 coordinate (-1 - all with overscan)
--Y1=arg absolute frame Y1 coordinate (-1 - all with overscan)
--async move stepper motor asynchronous
--brightness=arg CMOS brightness level
--camdevno=arg camera device number (if many: 0, 1, 2 etc)
--cancel cancel current exposition
--client run as client
--close-shutter close shutter
--focdevno=arg focuser device number (if many: 0, 1, 2 etc)
--gain=arg CMOS gain level
--help show this help
--host=arg server's host name
--imageport=arg INET image socket port (default: port+1)
--infty=arg start (!=0) or stop(==0) infinity capturing loop
--logfile=arg logging file name (if run as server)
--open-shutter open shutter
--plugin=arg common device plugin (e.g devfli.so)
--port=arg INET command socket port (omit if use on same host with server)
--restart restart image server
--rewrite rewrite output file if exists
--server run as server
--set-fan=arg set fan speed (0 - off, 1 - low, 2 - high)
--shutter-on-high run exposition on HIGH @ pin5 I/O port
--shutter-on-low run exposition on LOW @ pin5 I/O port
--viewer passive viewer (only get last images)
--wheeldevno=arg filter wheel device number (if many: 0, 1, 2 etc)
Notes:
- A UNIX command socket named
@ccd_captureis created/used automatically (abstract namespace, no file on disk). There is no--pathoption; the name is hardcoded insocket.hasUNIX_SOCK_NAME. - If neither
--portnor--imageportis given, the client receives images through shared memory (see-k/--shmkey). To force image transmission over INET, point--host,--portand/or--imageport(this replaces the removed--forceimsock). If server run without--port, there's only shared memory mechanism to grab images for client. - If
--portis given without--imageport, the latter is set toport+1automatically.
Image viewer
In image view mode you can display menu by clicking of right mouse key or use shortcuts:
- '0' - restore zoom;
- 'c' - capture new image in pause mode (works only with
-nflag); - 'e' - switch on/off histogram equalization;
- 'l' - flip image right-left;
- 'p' - pause or resume capturing (works only with
-nflag); - 'u' - flip image up-down;
- 'Z' - zoom+;
- 'z' - zoom-;
- 'Ctrl+r' - roll histogram conversion function (LOG, SQRT, POW, LINEAR);
- 'Ctrl+s' - save displayed image (works only if you pointed output file name or prefix);
- 'Ctrl+q' - exit.
Mouse functions:
- Left button - center selected point.
- Middle button - move image.
- Right button - show menu.
- Wheel up - scroll up, or scroll left (with Shift), or zoom+ (with Ctrl).
- Wheel down - scroll down, or scroll right (with Shift), or zoom- (with Ctrl).
Server
When you run the server you need at least to point:
- camera plugin (
-C libdev….so); - a way to accept commands:
- UNIX socket
@ccd_capture- always opened by the server; the local client connects to it by default when no--portis given; - optionally an INET command socket, via
--port=port;
- UNIX socket
- optionally an INET image socket, via
--imageport=port; if you point--portbut not--imageport, the latter defaults toport+1; - shared memory key for fast local image transmission,
-k=key(default:7777777).
To send commands to server you can use the client, netcat session, my
tty_term or any other tool. The server speaks a simple
line-based text protocol (send help to see the full list).
Protocol
Each request is a single line, terminated by \n:
key- getter or command without argumentskey=value- setter
The server answers with one line (or several, for help, camlist, foclist,
wlist):
OK- the command completed successfullyBUSY- cannot run the command now (camera is busy)FAIL- some error occurredBADKEY- unknown keyBADVAL- invalid value for the keykey=value- for getters (and setters, as echo of the new value)
Supported commands
| Command | Description |
|---|---|
brightness[=V] |
get/set camera brightness |
camdevno[=N] |
get/set active camera number |
camfanspeed[=N] |
get/set camera fan speed (0..2) |
camflags |
get flags: bit0 - start capture, bit1 - cancel, bit2 - restart server |
camlist |
list all connected cameras (one camlist='model' line per camera) |
confio[=N] |
configure I/O port |
dark[=0/1] |
don't open shutter on exposure (dark frames) |
expstate[=N] |
see below |
exptime[=V] |
get/set exposure time (s) |
fastspeed[=0/1] |
get/set fast readout mode |
focdevno[=N] |
get/set active focuser |
foclist |
list all connected focusers |
focmaxpos |
get maximal focuser position |
focminpos |
get minimal focuser position |
focpos[=V] |
get/set focuser position (mm) |
foctemp |
get focuser body temperature |
format[=X0,Y0,X1,Y1] |
get/set camera frame format |
gain[=V] |
get/set camera gain |
hbin[=N] |
get/set horizontal binning |
help |
show this help |
imnumber |
number of grabbed images since the server start |
imwidth / imheight |
width/height of the last image |
infty[=0/1] |
run/stop the infinity capturing loop |
io[=N] |
get/set I/O port state |
lowres[=0/1] |
run in 8-bit mode instead of 16-bit |
maxformat |
get maximal available frame format |
nflushes[=N] |
get/set number of pre-flushes |
plugincmd=KEY[=VAL] |
custom camera plugin command |
restartTheServer |
restart the server |
shmemkey |
get shared memory key |
shutter=N |
run shutter command (0=open, 1=close, 2=expose @HIGH, 3=expose @LOW) |
tcold[=V] |
get/set cold-side temperature; also returns tbody= and thot= if supported |
tremain |
remaining exposure time (s) |
vbin[=N] |
get/set vertical binning |
wdevno[=N] |
get/set active wheel |
wlist |
list all connected wheels |
wmaxpos |
get maximal wheel position |
wpos[=N] |
get/set wheel position |
wtemp |
get wheel body temperature |
expstate values:
0- idle (sendingexpstate=0cancels the current exposition);1- capturing (sendingexpstate=1starts an exposition);2- frame is ready (invalid for setter);3- error (invalid for setter).
Server doesn't sends to client any asynchronous data.
Custom plugin commands
Since version 1.2.0 a custom plugin command system is available. To list the available commands,
run the client/server with --plugincmd=help, or send plugincmd=help to a running server.
Commands can be procedures/flags (plugincmd=cmd) or setters/getters (plugincmd=key and
plugincmd=key=value).
To transmit these custom commands to the server use plugincmd=key[=value].
Client
To run the client you should point --client and the same port options as for
the server (command socket and image SHM key or image socket):
--host=HOST(optional) - server host name / IP for INET command socket;--port=PORT(optional) - INET command socket port; if omitted, the client connects to the UNIX socket@ccd_captureon the local host;--imageport=PORT(optional) - INET image socket port; if omitted, the client receives images through the shared memory segment-k/--shmkey;-k/--shmkey=KEY(optional) - shared memory key for image data.
Client modes:
- with
--viewer- opens the OpenGL viewer and passively receives images from the server (in this mode the client cannot start expositions); to produce images continuously the server must be set toinfty=1, or other clients must sendexpstate=1; - with
--display(or-D) - opens the OpenGL window and continuously requests server for new images (you should point--exptime=T(or-x T) for specific exposition time; - without viewer options - sends the given options to the server and exits;
if you specify
--outfile,--outfileprefixor--nframes>0, the client starts an exposition, waits for the image, and optionally saves it as FITS.
--forceimsock was removed; use --port and optionally --imageport to force image transfer over
INET socket instead of shared memory
Dummy camera plugin
The plugin simply emulates the acquisition process: images are a 2-D sinusoid with given periods, shifted by one pixel each frame.
Commands:
- px = (double) [1, inf] - set/get sin period over X axis (pix)
- py = (double) [1, inf] - set/get sin period over Y axis (pix)
Artifical star plugin
The plugin emulates a star field with up to MAX_STARS (32) stars. You can shift the center of the
field to emulate telescope correction and rotate the field to emulate derotation. All stars are
Moffat profiles with the same FWHM and scale parameters. Their coordinates (arcsec) are stored in
arrays x and y, with magnitudes in mag. You can emulate image drift, rotation, short-exposure
position fluctuations, and Poisson noise (lambda==1 means "no noise").
Two additional commands - mask and bkg - allow you to load a binary mask and a background
image. The background (8-bit monochrome) is added to the generated star field. The mask is then
AND-ed with the result: zero mask pixels force the output to zero, non-zero pixels are preserved.
After that, the bias level is added and (optionally) Poisson noise is applied to the full frame.
Commands:
- beta = (double) [0.5, inf] - Moffat
betaparameter - bias = (int) [0, 30000] - bias value
- bkg = (string) - load background image
- curstar = (int) [0, MAX_STARS-1] - set number of current star to change parameters
- fluct = (double) [0, 3] - stars position fluctuations (arcsec per sec)
- fwhm = (double) [0.1, 10] - stars min FWHM, arcsec
- lambda = (double) [1, inf] - Poisson noice lambda value (>1)
- lambda0 = (double) [1, inf] - Poisson noice lambda value (>1) for dark noise
- mag = (double) [-30, 30] - Next star magnitude: 0m is 0xffff/0xff (16/8 bit) ADUs per second
- mask = (string) - load mask image (binary, ANDed)
- nstars = (int) [1, MAX_STARS] - set amount of stars (not more than MAX_STARS)
- rotangle = (double) [0, 1.296e+06] - Starting rotation angle (arcsec)
- scale = (double) [0.001, 3600] - CCD scale: arcsec/pix
- vr = (double) [-36000, 36000] - rotation speed (arcsec/s)
- vx = (double) [-20, 20] - X axe drift speed (arcsec/s)
- vy = (double) [-20, 20] - Y axe drift speed (arcsec/s)
- x = (int) - X coordinate of next star (arcsec, in field coordinate system)
- y = (int) - Y coordinate of next star (arcsec, in field coordinate system)
- xc = (int) - x center of field in array coordinates
- yc = (int) - y center of field in array coordinates
Examples
ccd_client
Connects to the server, optionally enables infty, and takes up to N images (or quits if no
image is available for a few seconds).
Usage:
-N, --node=arg server's host (if working over net) or UNIX-socket path
-P, --import=arg image socket port (if not 'port+1'
-h, --help show this help
-i, --infty run in infinity capturing loop (else - request each frame)
-k, --shmkey=arg shared memory (with image data) key (default: 7777777)
-n, --nframes=arg make series of N frames
-p, --port=arg command socket port
-x, --exptime=arg set exposure time to given value (seconds!)
centroids / centroids16
Get images from the server (only over shared memory) and calculate the gravity center and moments
of the first-order/second-order brightness. centroids works only in 8-bit mode and centroids16
only in 16-bit mode.
Usage:
-N, --node=arg INET command socket host or UNIX socket name
-b, --background=arg fixed background level
-h, --help show this help
-i, --infty run in infinity capturing loop (else - request each frame)
-k, --shmkey=arg shared memory (with image data) key (default: 7777777)
-n, --nframes=arg make series of N frames (default: 10)
-o, --output=arg output file with T/x/y/w
-p, --port=arg port of INET command socket
-s, --sigmas=arg amount of sigmas [-5..15] added to image median for background calculation (default: 1)
-x, --exptime=arg set exposure time to given value (seconds!)
Option --sigmas works only for 16-bit version, as in 8-bit background calculation use
il_Image_background (calculates background by histogram curve).
Known issues
- The server requires at least one command socket (
@ccd_captureUNIX socket is always created; INET command socket is optional). - If both
--outfileand an output-file prefix (positional argument) are given, the program exits. - The image viewer uses OpenGL and freeglut; it needs an X11 display.
License
This repository is provided under the GNU General Public License v3 or later. Full text of the GPLv3 is available at https://www.gnu.org/licenses/gpl-3.0.html.