[Teem-commit] teem/src/gage shape.c,1.10,1.11

[Gordon K. <kin...@us...>]

Update of /cvsroot/teem/teem/src/gage
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv6688/gage

Modified Files:
	shape.c 
Log Message:
Two major changes, which were done simultaneously:
1) Some renamings related to NrrdAxis, nrrdAxisInfo, and so on
2) Addition of the nrrdKind information to the NrrdAxisInfo struct

In detail:
1) Some renamings related to NrrdAxis, nrrdAxisInfo, and so on:
struct:
NrrdAxis --> NrrdAxisInfo (NB: Nrrd struct still has field "axis")
functions:
nrrdAxisPos() --> nrrdAxisInfoPos()
nrrdAxisIdx() --> nrrdAxisInfoIdx()
nrrdAxisPosRange() --> nrrdAxisInfoPosRange()
nrrdAxisIdxRange() --> nrrdAxisInfoIdxRange()
nrrdAxisSpacingSet() --> nrrdAxisInfoSpacingSet()
nrrdAxisMinMaxSet() --> nrrdAxisInfoMinMaxSet()

Now, ANYTHING having to do with setting, getting, or manipulating the
meta-information about the axes starts with "nrrdAxisInfo".  The single
exception to this is that the Nrrd struct's "axis" field was not
renamed to "axisInfo", since this seemed more annoying that it was worth.

Also, (this isn't new) ANYTHING having to do the set of axes, the
shape of the array, or the per-axis ordering of samples, starts with
"nrrdAxes".  The nrrdAxes functions are NOT merely for manipulating
the per-axis meta information-- something about the array as a whole,
or the set of axes as a whole, is changing.  Yes, this means that
there's a function called "nrrdAxesInsert", even though it only
inserts a single axis, but I figured the consistency generated by
strict adherence to the nrrdAxes and nrrdAxisInfo prefixes would be
better in the long run.

2) Addition of the nrrdKind information to the NrrdAxisInfo struct
This is nrrd's latest and probably most dangerous step towards putting
real semantic information in the array representation (that is, the
"nearly raw" philosophy is getting stretched).  The best way to think
about this is that its a *hint*: an extra bit of information, kind of
like the label or the unit, that you may want to associated with the
axis, and which has a sufficiently general nature to warrent direct
representation.

So, new to the (newly renamed) NrrdAxisInfo struct:
  int kind;                      /* what kind of information is along this
                                    axis (from the nrrdKind* enum) */

Accordingly, there is change to the file format, which of course means
that the magic is once again incremented.  If you write a nrrd with
known kinds on any axis, the magic will be "NRRD0003".  The new kinds
field looks like (for-example)

  kinds: 3-color domain domain

for an RGB image.  Like other per-axis fields, its specification is
plural (its "kinds:", not "kind:"), and like centering, you use "???"
to mean, "I don't know", for example:

  kinds: ??? domain domain

To make this hint more useful, there's a new function nrrdKindSize()
which returns what nrrd thinks is the suggested axis size for the
different nrrdKind's.  This function will return 0 to indicate
"I have no advice for you on how big this axis should be".  The reason
for using 0 instead of -1 is that someday nrrd may change the axis size
type from int to unsigned int.

To offer some control of the nrrdKind behavior, there is a new global
"state" variable:  nrrdStateKindNoop.  Currently, this is AIR_TRUE by
defaul.  You can set it to AIR_FALSE to enable some minimal cleverness
on the part of nrrd.  The nature of that minimal cleverness is almost
certainly likely to change with time.

Due to the nature of nrrdAxisInfoCopy, anything which doesn't explicitly
ask the axis information NOT to be copied, will have it be copied.  For
example, nrrdSlice will propogate through the kinds on the axes that
it didn't touch, same with nrrdAxesPermute, and the like.

Regardless of NrrdKindStateNoop, the output of these functions will set
nrrdKindUnknown on all the axes that experienced a non-trivial change:
nrrdAxesSplit, nrrdAxesMerge, nrrdReshape, nrrdReshape_nva,
nrrdUnblock, nrrdJoin, nrrdApply1DLut, nrrdApply1DRegMap,
and nrrdApply1DIrregMap.

These functions respect nrrdKindStateNoop:
nrrdCrop, nrrdPad, nrrdShuffle, nrrdFlip, nrrdSpatialResample:
if (nrrdKindStateNoop) {
  If the axis operated on was not a nrrdKindDomain or nrrdKindList,
  the resulting kind is nrrdKindUnknown
  Else, the resulting kind is the same as the input kind.
  This is implemented through _nrrdKindAltered()
} else {
  output kind is a copy of the input kind
}
nrrdHisto, nrrdHistoAxis, nrrdHistoJoint:
if (nrrdKindStateNoop) {
  histogram axes are nrrdKindDomain
} else {
  histogram axes are nrrdKindUnknown
}
nrrdAxisInsert:
if (nrrdKindStateNoop) {
  new axis is nrrdKindStub
} else {
  new axis is nrrdKindUnknown
}

For the record, this is what this change entailed:
added:
- global int nrrdStateKindNoop
- nrrdKindSize()
- airEnum *nrrdKind (maps between strings like "3color" and nrrdKind* values)
- NRRD_KIND_MAX #define

augmented:
- NrrdAxisInfo struct (now has "kind" field)
- _nrrdFieldInteresting(), _nrrdSprintFieldInfo(), _nrrdFormatNRRD_write()
  with things relating to new field ("kinds:") and magic ("NRRD0003")
- _nrrdReadNrrdParseInfo[] parser callback, with new
  _nrrdReadNrrdParse_kinds()
- airEnum *nrrdField
- nrrdAxisInfo C enum (for passing to nrrdAxisInfo{Set,Get})
- nrrdField* C enum
- nrrdStateGetenv(): looks for NRRD_STATE_KIND_NOOP" environment variable

One annoying bit:

I didn't add a new flag to "unu make" to learn the axis kinds because
I *can't*.  This is a basic limitation in hest which is gotten pretty
annoying: there is direct way to see if an option was given on the command
line or not.  Every option has to have a value supplied, either via the
command-line or via the default value string, but once its all been parsed,
you don't know where it came from, and nor can you tell hest "this option
is really really optional, there is no default, and its okay if the user
never gives you a value."  This will only be fixed with a hest re-write.



Index: shape.c
===================================================================
RCS file: /cvsroot/teem/teem/src/gage/shape.c,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** shape.c	29 Mar 2004 21:26:48 -0000	1.10
--- shape.c	30 Mar 2004 19:25:01 -0000	1.11
***************
*** 74,78 ****
    char me[]="_gageShapeSet", err[AIR_STRLEN_MED];
    int i, ai, minsize, cx, cy, cz, sx, sy, sz, num[3], defCenter;
!   NrrdAxis *ax[3];
    double maxLen, xs, ys, zs, defSpacing;
  
--- 74,78 ----
    char me[]="_gageShapeSet", err[AIR_STRLEN_MED];
    int i, ai, minsize, cx, cy, cz, sx, sy, sz, num[3], defCenter;
!   NrrdAxisInfo *ax[3];
    double maxLen, xs, ys, zs, defSpacing;