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

[Alan W. I. <ir...@be...>]

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.

One unavoidable issue is whether we are willing to go through the necessary
API changes to get these problems fixed.  My own view is changes in API are
permissible so long as there is a compelling reason. In the present case a
common API rather than the present non-uniform API for passing 3D
information to our 3D routines is IMO already a compelling enough reason for
change. To be more specific the nx, ny issue above a compelling reason. For
years gnuplot has had the facility of allowing ny to be a function of x
index or nx be a function of y index for all 3D routines, and PLplot has
suffered in comparison.  I was willing to accept this PLplot limitation in
1995 because gnuplot axis labelling sucked in the 3D case, but that does not
have to mean we must accept this PLplot limitation indefinitely.

I should also emphasize if we do decide to change to a common 3D information
passing API, that we give a strong warning to our users.  I suggest the best
way to make such a strong warning is a special release of PLplot with just
the 3D information passing API change.  I would be happy to do that once the
present release is out the door and we have implemented the API change.

What I would like to encourage now is discussion of what the ideal 3D
information passing API should be with the discussion unconstrained by any
3D passing API decisions we have made in the past.  My C skills (such as
they are) have been solely developed by looking at code in PLplot so it is
hard for me to think outside that box in a creative way. However, I believe
the current 3D argument lists are way too cluttered with z, nx, ny, and x
and y index range limits. Surely all that stuff could be made part of the
general struct that is needed in any case to pass the 3D information to the
3D routine?  It should also be kept in mind that in general either nx is a
function of y index or ny is a function of x index.

Maurice, I know you have thought quite a bit about the problem of passing 3D
information to our 3D routines in the past and also the corresponding
problem for the 3D defined region information so I am hoping you will open
the discussion on what you think that ideal API should be.  I am also hoping
that your vision will be so compelling that your post will also effectively
close the ideal API discussion....;-)

Alan

email: ir...@be...
phone: 250-727-2902	FAX: 250-721-7715
snail-mail:
Dr. Alan W. Irwin
Department of Physics and Astronomy,
University of Victoria, P.O. Box 3055,
Victoria, British Columbia, Canada, V8W 3P6
__________________________

Linux-powered astrophysics
__________________________