Merge pull request #218 from glenco/nt/ds9

XPA support and basic DS9 integration. Closes #7.
glenco · Jan 19, 2016 · 9d4f68c · 9d4f68c
2 parents ce14643 + 9fae0fc
commit 9d4f68c
Show file tree

Hide file tree

Showing 12 changed files with 367 additions and 32 deletions.
diff --git a/Makefile b/Makefile
@@ -27,6 +27,21 @@
 #   MULTINEST_LIB                                                    #
 #     MultiNest library (e.g. `-lmultinest` or `-lnest3`)            #
 #                                                                    #
+#   XPA                                                              #
+#     build with XPA support for DS9 integration                     #
+#                                                                    #
+#   XPA_DIR                                                          #
+#     path to a local XPA build                                      #
+#                                                                    #
+#   XPA_INCLUDE_DIR                                                  #
+#     path to `xpa.h`                                                #
+#                                                                    #
+#   XPA_LIB_DIR                                                      #
+#     path to the XPA library                                        #
+#                                                                    #
+#   XPA_LIB                                                          #
+#     XPA library (e.g. `-lxpa`)                                     #
+#                                                                    #
 #   OPENCL_DIR                                                       #
 #     path to the OpenCL implementation                              #
 #                                                                    #
@@ -136,7 +151,9 @@ DEBUG_TAG =
 endif
 
 # CFITSIO library
-CFITSIO_LIB ?= -lcfitsio
+ifndef CFITSIO_LIB
+CFITSIO_LIB = -lcfitsio
+endif
 
 ifdef CFITSIO_DIR
 CFITSIO_INCLUDE_DIR = $(CFITSIO_DIR)
@@ -151,7 +168,9 @@ endif
 LDLIBS += $(CFITSIO_LIB)
 
 # MultiNest library
-MULTINEST_LIB ?= -lmultinest
+ifndef MULTINEST_LIB
+MULTINEST_LIB = -lmultinest
+endif
 
 ifdef MULTINEST_DIR
 MULTINEST_INCLUDE_DIR = $(MULTINEST_DIR)/include
@@ -165,10 +184,37 @@ LDFLAGS += -L$(MULTINEST_LIB_DIR) -Wl,-rpath,$(MULTINEST_LIB_DIR)
 endif
 LDLIBS += $(MULTINEST_LIB)
 
+# build with XPA support
+ifdef XPA
+
+CFLAGS += -DLENSED_XPA
+
+# XPA library
+ifndef XPA_LIB
+XPA_LIB = -lxpa
+endif
+
+ifdef XPA_DIR
+XPA_INCLUDE_DIR = $(XPA_DIR)
+XPA_LIB_DIR = $(XPA_DIR)
+endif
+ifdef XPA_INCLUDE_DIR
+CFLAGS += -I$(XPA_INCLUDE_DIR)
+endif
+ifdef XPA_LIB_DIR
+LDFLAGS += -L$(XPA_LIB_DIR) -Wl,-rpath,$(XPA_LIB_DIR)
+endif
+LDLIBS += $(XPA_LIB)
+
+# ifdef XPA
+endif
+
 # system-dependent OpenCL library
 OPENCL_LIB_Linux = -lOpenCL
 OPENCL_LIB_Darwin = -framework OpenCL
-OPENCL_LIB ?= $(OPENCL_LIB_$(OS))
+ifndef OPENCL_LIB
+OPENCL_LIB = $(OPENCL_LIB_$(OS))
+endif
 
 ifdef OPENCL_DIR
 OPENCL_INCLUDE_DIR = $(OPENCL_DIR)/include
@@ -264,6 +310,10 @@ cache:
 	@$(ECHO) "MULTINEST_INCLUDE_DIR = $(MULTINEST_INCLUDE_DIR)" >> $(CACHE)
 	@$(ECHO) "MULTINEST_LIB_DIR = $(MULTINEST_LIB_DIR)" >> $(CACHE)
 	@$(ECHO) "MULTINEST_LIB = $(MULTINEST_LIB)" >> $(CACHE)
+	@$(ECHO) "XPA = $(XPA)" >> $(CACHE)
+	@$(ECHO) "XPA_INCLUDE_DIR = $(XPA_INCLUDE_DIR)" >> $(CACHE)
+	@$(ECHO) "XPA_LIB_DIR = $(XPA_LIB_DIR)" >> $(CACHE)
+	@$(ECHO) "XPA_LIB = $(XPA_LIB)" >> $(CACHE)
 	@$(ECHO) "OPENCL_INCLUDE_DIR = $(OPENCL_INCLUDE_DIR)" >> $(CACHE)
 	@$(ECHO) "OPENCL_LIB_DIR = $(OPENCL_LIB_DIR)" >> $(CACHE)
 	@$(ECHO) "OPENCL_LIB = $(OPENCL_LIB)" >> $(CACHE)

diff --git a/README.md b/README.md
@@ -66,6 +66,13 @@ for a quick look at results, one could invoke Lensed in the following way:
 
 As before, the order of the given configuration files and options is important.
 
+If Lensed is [built with XPA support](docs/building.md), direct updating of the
+reconstruction progress in SAOImage DS9 is available.
+
+    $ lensed config.ini --ds9=true
+
+This enables basic DS9 integration in Lensed.
+
 
 License
 -------

diff --git a/docs/building.md b/docs/building.md
@@ -96,6 +96,12 @@ If these dependencies are installed in a system-wide, default-accessible path,
 Lensed should be able to find them without any further intervention. For more
 information, refer to the [dependencies page](dependencies.md).
 
+For XPA support and DS9 integration, the
+
+-   XPA header and library
+
+is additionally required.
+
 
 Build configuration
 -------------------
@@ -120,6 +126,11 @@ The following variables can be passed to Lensed:
 | `MULTINEST_INCLUDE_DIR` | path to `multinest.h`                             |
 | `MULTINEST_LIB_DIR`     | path to the MultiNest library                     |
 | `MULTINEST_LIB`         | MultiNest library (e.g. `-lmultinest`, `-lnest3`) |
+| `XPA`                   | build with XPA support for DS9 integration        |
+| `XPA_DIR`               | path to a local XPA build                         |
+| `XPA_INCLUDE_DIR`       | path to `xpa.h`                                   |
+| `XPA_LIB_DIR`           | path to the XPA library                           |
+| `XPA_LIB`               | XPA library (e.g. `-lxpa`)                        |
 | `OPENCL_DIR`            | path to the OpenCL implementation                 |
 | `OPENCL_INCLUDE_DIR`    | path to the `CL/cl.h` header                      |
 | `OPENCL_LIB_DIR`        | path to the OpenCL library                        |
@@ -157,6 +168,11 @@ be undefined by calling `make DEBUG=` (i.e. with no value). Debug symbols and
 optimisations are set for each individual object file at compile time, hence
 it is necessary to perform a `make clean` in order to fully apply the setting.
 
+The XPA support and DS9 integration is controlled with the `XPA` symbol. Since
+XPA requires an additional [dependency](dependencies.md#xpa), it is by default
+not supported. Calling `make XPA=1` enables XPA support and DS9 integration.
+The XPA library can be [configured](#xpa) like any other dependency.
+
 The following sections contain further details on configuring the individual
 components of Lensed.
 
@@ -181,8 +197,8 @@ $ make CFITSIO_INCLUDE_DIR="$HOME/headers" CFITSIO_LIB_DIR="$HOME/libraries"
 ```
 
 The default CFITSIO library be linked is `-lcfitsio`. This can be overridden
-using the `CFITSIO_LIB` flag, either giving `-l<name>` linker flag or the full
-path to the library.
+using the `CFITSIO_LIB` flag, either a giving `-l<name>` linker flag or the
+full path to the library.
 
 ```sh
 $ make CFITSIO_LIB="$HOME/libraries/my-cfitsio-lib.a"
@@ -226,6 +242,39 @@ $ make MULTINEST_INCLUDE_DIR="/path/to/multinest/example_eggbox_C" \
 ```
 
 
+### XPA
+
+To enable XPA support and DS9 integration, use the `XPA` flag.
+
+```sh
+$ make XPA=1
+```
+
+If XPA has been built from source, the path to the source folder can be given
+to Lensed using the `XPA_DIR` variable.
+
+```sh
+$ make XPA_DIR="$HOME/xpa"
+```
+
+This sets both `XPA_INCLUDE_DIR` and `XPA_LIB_DIR` to `XPA_DIR`, as this is 
+where `xpa.h` and `libxpa` reside by default.
+
+Alternatively, `XPA_INCLUDE_DIR` and `XPA_LIB_DIR` can be explicitly specified.
+
+```sh
+$ make XPA_INCLUDE_DIR="$HOME/headers" XPA_LIB_DIR="$HOME/libraries"
+```
+
+The default XPA library be linked is `-lxpa`. This can be overridden using the
+`XPA_LIB` flag, either giving a `-l<name>` linker flag or the full path to the
+library.
+
+```sh
+$ make XPA_LIB="$HOME/libraries/my-xpa-lib.a"
+```
+
+
 ### OpenCL
 
 *

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -13,6 +13,8 @@ offset      = 2.9633
 output      = true
 root        = chains/double-lens-
 
+ds9         = true
+
 [objects]
 lens        = sie
 source      = sersic
@@ -88,6 +90,14 @@ Option     | Type           | Description                            | Default
 
 Options without a default value are required to be set in the configuration.
 
+If (and only if) XPA support is enabled in the [build options](building.md),
+there are a number of additional settings for integration with SAOImage DS9:
+
+Option     | Type           | Description                            | Default
+-----------|----------------|----------------------------------------|--------
+`ds9`      | `bool`         | Integrate with SAOImage DS9.           | `false`
+`ds9-name` | `string`       | XPA template name for DS9.             | `ds9`
+
 There are a number of caveats regarding the following options.
 
 ### device

diff --git a/docs/dependencies.md b/docs/dependencies.md
@@ -10,6 +10,13 @@ Lensed has a number of compile-time dependencies, namely
 If these dependencies are installed in a system-wide, default-accessible path,
 Lensed should be able to find them without any further intervention.
 
+For XPA support and integration with SAOImage DS9, there is a further
+dependency on
+
+-   [XPA](#xpa) .
+
+XPA support must be enabled explicitly in the [build options](building.md).
+
 
 CFITSIO
 -------
@@ -187,3 +194,56 @@ Some useful links are
 
 Mac OS X ships with the libraries and headers required to build OpenCL programs
 by default.
+
+
+XPA
+---
+
+For XPA support and DS9 integration, the
+
+- [XPA library](https://github.com/ericmandel/xpa)
+
+is required.
+
+
+### Sources
+
+The XPA library and command line tools can be install quickly from the GitHub
+repository:
+
+```sh
+$ curl -L https://github.com/ericmandel/xpa/archive/master.tar.gz | tar xz
+$ cd xpa-master
+$ ./configure  # --prefix=... and other options as necessary
+$ make
+```
+
+For use with Lensed, it is not necessary to have X11 or Tcl integration.
+
+```sh
+$ ./configure --without-x --without-tcl  # --prefix=...
+$ make
+```
+
+If possible, the XPA libraries and command line tools should be installed into
+the system, using
+
+```sh
+$ sudo make install
+```
+
+or similar, depending on the platform at hand.
+
+
+### Packages
+
+#### Mac OS X (Homebrew)
+
+Under Mac OS X, the library can be installed using Homebrew from the official 
+X11 repository. Please note that this currently requires an installation of
+XQuartz, even though building from source does not (see above).
+
+```sh
+$ brew install homebrew/x11/xpa
+```
+
diff --git a/src/data.c b/src/data.c
@@ -84,14 +84,9 @@ void read_fits(const char* filename, int datatype, size_t* width, size_t* height
         fits_error(filename, status);
 }
 
-void write_fits(const char* filename, int datatype, size_t width, size_t height,
-                size_t num, void** images)
+void write_fits(fitsfile* fptr, int datatype, size_t width, size_t height,
+                size_t num, void** images, int* status)
 {
-    int status = 0;
-
-    // the FITS file
-    fitsfile* fptr;
-
     // total number of pixels
     long npix = width*height;
 
@@ -102,28 +97,14 @@ void write_fits(const char* filename, int datatype, size_t width, size_t height,
     // writing offset
     long fpixel[2] = { 1, 1 };
 
-    // create FITS file
-    fits_create_file(&fptr, filename, &status);
-    if(status)
-        fits_error(filename, status);
-
     for(size_t n = 0; n < num; ++n)
     {
         // create image extension
-        fits_create_img(fptr, DOUBLE_IMG, naxis, naxes, &status);
-        if(status)
-            fits_error(filename, status);
+        fits_create_img(fptr, FLOAT_IMG, naxis, naxes, status);
 
         // write pixels
-        fits_write_pix(fptr, datatype, fpixel, npix, images[n], &status);
-        if(status)
-            fits_error(filename, status);
+        fits_write_pix(fptr, datatype, fpixel, npix, images[n], status);
     }
-
-    // close file
-    fits_close_file(fptr, &status);
-    if(status)
-        fits_error(filename, status);
 }
 
 void read_image(const char* filename, size_t* width, size_t* height, cl_float** image)
@@ -294,8 +275,51 @@ void read_psf(const char* filename, size_t* width, size_t* height, cl_float** ps
 
 void write_output(const char* filename, size_t width, size_t height, size_t noutput, cl_float* output[])
 {
+    int status = 0;
+
+    // the FITS file
+    fitsfile* fptr;
+
+    // create FITS file
+    fits_create_file(&fptr, filename, &status);
+
     // write FITS file
-    write_fits(filename, TFLOAT, width, height, noutput, (void**)output);
+    write_fits(fptr, TFLOAT, width, height, noutput, (void**)output, &status);
+
+    // close FITS file
+    fits_close_file(fptr, &status);
+
+    // report FITS errors
+    if(status)
+        fits_error(filename, status);
+}
+
+size_t write_memory(void** mem, size_t width, size_t height, size_t noutput, cl_float* output[])
+{
+    int status = 0;
+
+    // memory block
+    *mem = NULL;
+    size_t siz = 0;
+
+    // the FITS file
+    fitsfile* fptr;
+
+    // create in-memory FITS
+    fits_create_memfile(&fptr, mem, &siz, 0, realloc, &status);
+
+    // write in-memory FITS
+    write_fits(fptr, TFLOAT, width, height, noutput, (void**)output, &status);
+
+    // close in-memory FITS
+    fits_close_file(fptr, &status);
+
+    // report FITS errors
+    if(status)
+        fits_error(NULL, status);
+
+    // return the in-memory FITS
+    return siz;
 }
 
 void find_mode(size_t nvalues, const cl_float values[], const cl_float mask[], double* mode, double* fwhm)