The C library
libarcsec is arcsec as a library for C and C++ programs. Hand it the pixels of an
image (or the path of a FITS, XISF, ASDF, JPEG, PNG or TIFF file) and a rough idea of the field, and it
returns a FITS WCS: CRVAL, CRPIX, the CD matrix and, if you ask, SIP distortion terms.
It makes the same choices the command line does, and reads the same catalogues from the
same place, so a user who has run arcsec catalog install needs to configure nothing.
The full reference is the header,
arcsec.h,
where every function and field is documented, and the library’s
README.
Get it
Section titled “Get it”Each release has a library archive
per platform beside the program’s, named arcsec-lib-v<version>-<platform>:
| Platform | Archive | Holds |
|---|---|---|
| Linux (x86-64, arm64), glibc 2.35+ | .tar.gz |
libarcsec.so.1, libarcsec.a |
| macOS (Apple silicon) | .tar.gz |
libarcsec.dylib, libarcsec.a |
| Windows (x86-64) | .zip |
bin/arcsec.dll, lib/arcsec.lib, lib/arcsec_static.lib |
Every archive also has include/arcsec.h, a pkg-config file (lib/pkgconfig/arcsec.pc)
and a CMake package (lib/cmake/arcsec/), all of which find the files relative to
themselves, so the tree can be unpacked anywhere.
To build it yourself you need Rust 1.96 or newer and a C compiler:
git clone https://github.com/cruzzil/arcsec && cd arcseclibarcsec/dist.sh /tmp/arcsec # the same tree, in /tmp/arcsecsudo cp -a /tmp/arcsec/. /usr/local/ # to install it (then sudo ldconfig on Linux)The library’s source is also on crates.io as
libarcsec, for packagers who build from
published sources; its dist.sh makes the same tree.
Link it
Section titled “Link it”# pkg-config (also Meson's dependency('arcsec'))cc app.c $(pkg-config --cflags --libs arcsec)# CMake, with CMAKE_PREFIX_PATH pointing at the treefind_package(arcsec 0.7 REQUIRED)target_link_libraries(app PRIVATE arcsec::arcsec) # or arcsec::arcsec_staticA first program
Section titled “A first program”#include <arcsec.h>#include <stdio.h>
int solve(const float *pixels, uint32_t width, uint32_t height) { arcsec_image image = {0}; image.struct_size = sizeof image; image.data = pixels; /* row 0 is FITS row 1 */ image.pixel_type = ARCSEC_PIXEL_F32; image.width = width; image.height = height;
arcsec_solve_options opts; arcsec_solve_options_init(&opts); /* the command line's defaults */ opts.has_hint = 1; opts.ra_deg = 83.82; opts.dec_deg = -5.39; opts.search_radius_deg = 10.0; opts.pixel_scale_arcsec = 1.2;
arcsec_solver *solver = arcsec_solver_new(); arcsec_result *result = NULL; arcsec_status st = arcsec_solve(solver, &image, &opts, &result); if (st == ARCSEC_OK) { arcsec_wcs wcs = {0}; wcs.struct_size = sizeof wcs; arcsec_result_wcs(result, &wcs); printf("RA %.5f, Dec %.5f, %.3f\"/px\n", wcs.crval1, wcs.crval2, wcs.pixel_scale_arcsec); } else { fprintf(stderr, "%s: %s\n", arcsec_status_string(st), arcsec_last_error()); } arcsec_result_free(result); arcsec_solver_free(solver); return st;}What it offers
Section titled “What it offers”- Solving from pixels in memory (8-, 16- and 32-bit integers,
float,double; one or several planes, which are averaged; any row stride) or from a file, with a position hint or blind with an index. Options cover everything the command line has: search radius, field size or pixel scale (searched for when unknown, and, withfov_search, when the one given does not solve), star database, blind index, star count, binning, threads, SIP. - Results: the WCS as numbers or as 80-character FITS header cards, the matched star pairs, pixel↔sky conversion through the solution, and how the solve went.
- Star analysis without solving (
arcsec --analyse): star count, median HFD, and the stars. - Catalogue queries: where catalogues are installed, which database suits a field, whether a blind index is available.
- Callbacks: log messages, progress (stage and fraction of the search), and cancellation, from any thread.
- Memory. The library frees only what it allocated, through
arcsec_solver_freeandarcsec_result_free; everything you pass in or have it fill is yours. Images and strings are read during the call and not kept. - Threads. Separate solver handles may solve at the same time on separate threads,
each with its own thread budget. One handle runs one solve at a time
(
ARCSEC_BUSYotherwise).arcsec_solver_cancelworks from any thread. Callbacks run on arcsec’s worker threads and must be thread-safe. - Errors. Calls return an
arcsec_statuswhose solve codes match the command line’s exit codes (0 solved, 1 no solution, 2 too few stars, 16 file, 32 and 33 database), plus invalid argument, cancelled, busy and internal error; the message is inarcsec_last_error(). A crash inside arcsec is caught and reported asARCSEC_INTERNAL_ERROR, never propagated into your program. - Versions. Structs start with
struct_size, so fields can be added without breaking programs built against an older header. A breaking change raisesARCSEC_ABI_VERSION, which is also the number in the Linux soname (libarcsec.so.1).