WCSLIB 5.17

PGSBOX

`PGSBOX`, which is provided as a separate part of WCSLIB, is a PGPLOT routine (PGPLOT being a Fortran graphics library) that draws and labels curvilinear coordinate grids. Example `PGSBOX` grids can be seen at http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/PGSBOX/index.html.

The prologue to pgsbox.f contains usage instructions. pgtest.f and cpgtest.c serve as test and demonstration programs in Fortran and C and also as well- documented examples of usage.

`PGSBOX` requires a separate routine, `EXTERNAL` `NLFUNC`, to define the coordinate transformation. Fortran subroutine `PGCRFN` (pgcrfn.f) is provided to define separable pairs of non-linear coordinate systems. Linear, logarithmic and power-law axis types are currently defined; further types may be added as required. A C function, pgwcsl_(), with Fortran-like interface defines an `NLFUNC` that interfaces to WCSLIB 4.x for `PGSBOX` to draw celestial coordinate grids.

PGPLOT is implemented as a Fortran library with a set of C wrapper routines that are generated by a software tool. However, `PGSBOX` has a more complicated interface than any of the standard PGPLOT routines, especially in having an `EXTERNAL` function in its argument list. Consequently, `PGSBOX` is implemented in Fortran but with a hand-coded C wrapper, cpgsbox().

As an example, in this suite the C test/demo program, cpgtest, calls the C wrapper, cpgsbox(), passing it a pointer to pgwcsl_(). In turn, cpgsbox() calls `PGSBOX`, which invokes pgwcsl_() as an `EXTERNAL` subroutine. In this sequence, a complicated C struct defined by cpgtest is passed through `PGSBOX` to pgwcsl_() as an `INTEGER` array.

While there are no formal standards for calling Fortran from C, there are some fairly well established conventions. Nevertheless, it's possible that you may need to modify the code if you use a combination of Fortran and C compilers with linkage conventions that differ from that of the GNU compilers, gcc and g77.