This section applies to the user-supplied routines as part of a PaPCo module.
The only restriction here is that data must eventually end up in a form that can be accessed by an IDL plotting routine for that data, either in an IDL COMMON block (preferred) or passed by argument. IDL offers several options for this:
call_external; this is the IDL method of calling subroutines from
external relocatable object files. Note: the call_external procedure
will be dependent on the platform specific installation of Fortran and/or C,
and in general is not easily portable even between identical workstations.
The user can decide for himself whichever method involves the least amount of work. To make the read part of the module more portable it is advised to have the location (directory) of the data set via an environmental variable.
Current read-routines use an error-checking method which allows PaPCo to
``crash softly'' if it can't find data or there was a problem in reading it.
This is done via an error-common block. It is up to the user to decide the
extent of error checking he wants to put into his read-routine. At least the
common block get_err_no variable has to be set to zero if there is no
error checking done.
From PaPCo 09 onwards, PaPCo attempts to trap any errors that occur in any of the user-supplied routines. Instead of a plot an error message is then displayed. As this does not allow tracing of errors outside thePaPCo core this feature is one of the configurable defaults - turning error trapping off will then allow your routine to crash and you can perform error tracing.
Since PaPCo works by defining a time range to plot, it makes sense to write a wrapper routine for the data read which will utilize this time information to automatically read in data for that time and concatenate data together over periods longer than one file. It is up to the user to write a ``clever'' reading routine for his specific data. An example of such a reading routine can be found in the Los Alamos module and is described in Section 5.6.
NOTE:
PaPCo prescribes nothing about data format, variables, timing resolution or data product that you choose: Since it's your plotting routine that will plot the data, PaPCo doesn't care!
The only restrictions for the plotting routines is that they are in IDL and have access to the data from the read-routine. Current modules work via COMMON blocks, but this is not a requirement. The idea was to be able to ``remember'' which data had already been read, which allows relative quick zooming across a number of large data sets once they are in memory. Further, the routine must be able to plot a given time range which is supplied by PaPCo. PaPCo originally worked internally in seconds since 1990 (a relict of CRRES processing), but now uses an MJDT format (modified Julian Date plus seconds since the start of that day), so that there are no time restrictions anymore. PaPCo provides many conversion utilities to change both MJDT and the old T90 to more common formats.
There are very few essential lines that have to be included into your plotting routine to make it work with PaPCo. Any plotting routine that produces a plot in a coordinate system can be used and will be scaled by PaPCo to fit into the panel chosen by the user. PaPCo prescribes nothing about the appearance of your plot, number of tick marks and labeling, etc.
However, to be compatible with all other modules and to produce plots with some uniformity, all existing plotting routines follow a common plotting philosophy (see Section 5.3), and for which a template has been written. In practice, these conventions apply only to the ``dressing'' around a plot and are implemented easily and quickly. This is described in more detail in Section 5.3.
Since IDL provides one color table at a time, some effort has been undertaken to provide the user with more than one color table for SIMULTANEOUS use. PaPCo subdivides the normal color table into 4 sub-tables plus some fixed primary colors for use in color line plots. User routines are provided to manage these color tables.
This means that any color plot routine that the user wants to use should work with this color table scheme - otherwise the colors for all the other modules might be messed up. Again, this is not a fixed requirement - however, to work well with the other modules adherence to the PaPCo color scheme is strongly advised. More details are in Section 5.4.
PaPCo supplies a color plot routine which is compliant with the PaPCo color scheme. This is a fairly advanced and sophisticated routine which allows the user to to plot xyz plots where z is represented by a color scale, and both the x and y bin sizes can be variable. This routine is described in more detail in Section C.1.
PaPCo provides some built-in functionality via the mouse, called ``slices''. Here again PaPCo provides the functionality: it is up to the user to make use of it; the user ``tells'' PaPCo in his user-written module which of the slice functions he wants to support.
The idea here is to be able to launch some function or application by using the mouse - by moving the mouse pointer over a drawn panel and clicking in it. The are several PaPCo slice functions built into PaPCo - some of which should always work once enabled, such as the zoom and hair-cursor function, and others which require a user-written application, for which there are templates provided.
A typical slice might be a separate spectrum line plot for a single time when the user points his mouse into a spectrum color plot; another one calls up the level zero analysis tool for that product at that time. Adding slice-support to your module is considered ``advanced PaPCo '' and should only be done once the user has a good feel for the package.
There is also a mechanism for adding a completely new slice type to PaPCo, so called ``user slices''. The only limitation here is that PaPCo can currently support a maximum of 16 slices (PaPCo plus user slices). You can configure PaPCo with any combination of PaPCo plus user slices. This is definitely advanced PaPCo, but offers great power to the user to add in any functionality that he/she wants. Here you can not only define the mouse action you want, but also what action is taken in the draw window. For that you can choose from a range of PaPCo supplied draw window actions, such as ``draw vertical line'' or ``draw haircursor'' or ``drag box'', or you can write your own draw window action! Adding your own user-written draw window action is considered ``definitely advanced PaPCo''.