Re: [Plplot-devel] Revision needed for our API for passing 3D information to our 3D routines

[Maurice L. <mj...@ga...>]

Alan W. Irwin writes:
 > After this next release is out the door I hope to make some substantial
 > changes in how we call our current 3D routines, plot3d, plmesh, plsurf3d,
 > plcont, plshade, and plshades.
 > 
 > Currently we have a nonuniform mixture of API's for the way we pass 3D
 > information to our 3D routines. For example, many routines don't worry about
 > a defined region and plcont and plshade(s) have a generalized method of
 > passing z, x, y which allows using arbitrary methods (e.g., pltr0, pltr1,
 > pltr2, etc.) of evaluating the data while the rest of the routines (plot3d,
 > plmesh, plsurf3d) don't use a generalized method of passing 3D information
 > so their capabilities are much more limited as a result.
 > 
 > This lack of a generalized method of passing 3D information to plot3d,
 > plmesh, and plsurf3d has become a real problem for my own research work.
 > Typically my z arrays are defined with either fixed nx and ny a function of
 > x index or fixed ny with nx a function of y index.  It should not be a
 > problem for me to define more pltr variations that will handle these cases,
 > but the lack of a generalized method of passing information to plot3d,
 > plmesh, and plsurf3d also needs to be addressed as well.

I personally don't use surface plotting very often, as the data I deal with
tends to be a tad too noisy for it to be useful.  So I never got around to
generalizing these.

As for what an "uber-API" for these would look like, we can look at the API
for the fattest plcont/plshade plot calls we have and go from there.  For
contours:

plfcont(PLFLT (*f2eval) (PLINT, PLINT, PLPointer), 
        PLPointer f2eval_data, 
        PLINT nx, PLINT ny, PLINT kx, PLINT lx, 
        PLINT ky, PLINT ly, PLFLT *clevel, PLINT nlevel, 
        void (*pltr) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer), 
        PLPointer pltr_data);

and for shades:

plshade_int(PLFLT (*f2eval) (PLINT, PLINT, PLPointer), 
        PLPointer f2eval_data, 
        PLFLT (*c2eval) (PLINT, PLINT, PLPointer), 
        PLPointer c2eval_data,  
        PLINT (*defined) (PLFLT, PLFLT), 
        PLFLT missing_min, PLFLT missing_max, 
        PLINT nx, PLINT ny,  
        PLFLT xmin, PLFLT xmax, PLFLT ymin, PLFLT ymax, 
        PLFLT shade_min, PLFLT shade_max, 
        PLINT sh_cmap, PLFLT sh_color, PLINT sh_width, 
        PLINT min_color, PLINT min_width, 
        PLINT max_color, PLINT max_width, 
        void (*fill) (PLINT, PLFLT *, PLFLT *), PLINT rectangular, 
        void (*pltr) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer), 
        PLPointer pltr_data); 

(gulp).  The shade plotter has the exclusion region that the contour plotter
is missing, so if that capability were added to the contourer the two could
share that in common.  Possibly with the (*defined) argument changed to:

        void (*defined) (PLFLT, PLFLT, PLINT *, PLPointer), 
        PLPointer defined_data); 

as I mentioned some time back (but never got around to doing it).

'Course the real trick is to define simpler front-ends that do the job at hand
80%-95% of the time.  So plshades() is a step in the right direction.  Also
the kx, lx, ky, ly args in the contour plotter are rarely exercised so I'd
personally leave them out of a simpler general-purpose API (they were there in
plplot 2.6 and I left them in).  The way I look at it is: as long as you can
get at the "fat" API in C, someone facing a special need can always code up a
special interface routine for whatever binding they employ.

I also firmly believe that preserving the existing API should be a priority,
except when dealing with relatively newly-added calls for which some period
of flux is to be expected.  People use different versions of plplot on
different machines; you don't want them to be *too* afraid to upgrade.

-- 
Maurice LeBrun    mj...@ga...
Research Organization for Information Science and Technology of Japan (RIST)