[Teem-commit] SF.net SVN: teem:[6196] teemdoc/trunk/html/tree

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

Revision: 6196
          http://sourceforge.net/p/teem/code/6196
Author:   kindlmann
Date:     2014-07-11 03:45:59 +0000 (Fri, 11 Jul 2014)
Log Message:
-----------
synching with Teem

Modified Paths:
--------------
    teemdoc/trunk/html/tree/README.txt
    teemdoc/trunk/html/tree/src/TODO.txt

Modified: teemdoc/trunk/html/tree/README.txt
===================================================================
--- teemdoc/trunk/html/tree/README.txt	2014-07-11 03:40:30 UTC (rev 6195)
+++ teemdoc/trunk/html/tree/README.txt	2014-07-11 03:45:59 UTC (rev 6196)
@@ -1,6 +1,6 @@
-=============== 
-  Teem: Tools to process and visualize scientific data and images              
-  Copyright (C) 2012, 2011, 2010, 2009  University of Chicago
+===============
+  Teem: Tools to process and visualize scientific data and images
+  Copyright (C) 2013, 2012, 2011, 2010, 2009  University of Chicago
   Copyright (C) 2008, 2007, 2006, 2005  Gordon Kindlmann
   Copyright (C) 2004, 2003, 2002, 2001, 2000, 1999, 1998  University of Utah
 
@@ -27,7 +27,7 @@
 "LICENSE.txt" in the "src" directory.  The SLUL is the GNU Lesser
 General Public License, plus an exception: statically-linked binaries
 that link with Teem can be destributed under the terms of your choice,
-with very modest provisions.  
+with very modest provisions.
 
 =============== How to compile
 
@@ -42,7 +42,7 @@
 =============== Directory Structure
 
 * src/
-  With one subdirectory for each of the teem libraries, all the 
+  With one subdirectory for each of the teem libraries, all the
   source for the libraries is in here.  See library listing below.
   The src/CODING.txt file documents Teem coding conventions.
   * src/make
@@ -73,9 +73,9 @@
   subdirectories, with a name which exactly matches valid settings
   for the environment variable TEEM_ARCH. Within these directories are:
   * lib/
-    all libraries put both their static/archive (.a) and 
+    all libraries put both their static/archive (.a) and
     shared/dynamic (.so) library files here (such as libnrrd.a)
-  * bin/ 
+  * bin/
     all libraries put their binaries here, hopefully in a way which
     doesn't cause name clashes
   * obj/
@@ -89,7 +89,7 @@
     Bindings for python via ctypes
 
 * Examples/
-  Place for examples of Teem-using programs, but unfortunately 
+  Place for examples of Teem-using programs, but unfortunately
   not populated by much right now.  A work in progress.
 
 =============== Teem libraries
@@ -100,12 +100,12 @@
 
 * air: Basic utility functions, used throughout Teem
 
-* hest: Command-line parsing (air) 
+* hest: Command-line parsing (air)
 
 * biff: Accumulation of error messages (air)
 
 * nrrd: Nearly Raw Raster Data- library for raster data manipulation,
-and support for NRRD file format (biff, hest, air) 
+and support for NRRD file format (biff, hest, air)
 
 * ell: Linear algebra: operations on vectors, matrices and quaternions,
 and solving cubic polynomials. (nrrd, biff, air)
@@ -155,7 +155,7 @@
 * mite: Hoover-based volume rendering with gage-based transfer functions
 (ten, hoover, limn, gage, ell, nrrd, biff, air)
 
-* meet: Uniform API to things common to all Teem libraries 
+* meet: Uniform API to things common to all Teem libraries
 (mite, push, coil, pull, elf, ten, seek, hoover, echo, limn, bane, dye,
 gage, tijk, moss, alan, unrrdu, ell, nrrd, biff, hest, air)
 

Modified: teemdoc/trunk/html/tree/src/TODO.txt
===================================================================
--- teemdoc/trunk/html/tree/src/TODO.txt	2014-07-11 03:40:30 UTC (rev 6195)
+++ teemdoc/trunk/html/tree/src/TODO.txt	2014-07-11 03:45:59 UTC (rev 6196)
@@ -1,3 +1,8 @@
+** Compared to what's in HELP.txt, these are more generally more
+** fine-grained and nit-picky; some of them are only sensibly done by
+** GLK.  The things listed for Teem 2.0 involve significant API
+** changes, or significantly thoughtful redesign of how functional
+** components of Teem are implemented.
 
 ========
 for Teem 2.0:
@@ -2,5 +7,2 @@
 
-teem/include/teemEndian.h should NOT be setting TEEM_ENDIAN; it should
-be set by the build system.
-
 decide on a uniform way of indicating if a given external is available
@@ -24,13 +26,31 @@
 pointers, but to all values as well.
 
 all:
-* scrutinize use of strncpy, consider using airStrcpy
 * remove '_'s from enum value names in non-elf non-tijk libraries
 * decide if <LIB>_EXPORT should just be TEEM_EXPORT
 * enforce consistent use of AIR_CALLOC/AIR_MALLOC
+* decide consistent API of Copy() functions, or if consistency is needed, eg:
+  nrrdCopy() vs gageContextCopy()
+* decide consistent API of Compare vs Equal() functions, or if consistency
+  is needed, eg:
+  nrrdCompare() vs nrrdKernelCompare() vs nrrdKernelSpecCompare()
+    vs gageShapeEqual() vs gageStackBlurParmEqual().
+  Should these all have "name" params, or none, and how should we modify
+  names passed to sub-compare functions?
+  What else would benefit from such a Compare() or Equal() function?
 
 air:
+* find and use a good sscanf/printf replacement. Current annoyances:
+  - not being able to ask, "will sprintf'ingt this take up more than
+  this pre-allocated buffer", and "allocate this for as big as you need
+  to sprintf this".
+  - using airSingleScanf and airSinglePrintf for correctly handling
+  "inf", "-inf", "nan", and now "pi" on parsing.  And this will be a
+  place to handle setlocale weirness.  However, the "Single"
+  restriction is too cumbersome.
 * consider nixing AIR_ENDIAN, AIR_QNANHIBIT, and AIR_DIO
+* Hey, what does airSinglePrintf do with the common "%.17g" for a double?
+  It seems to not have the smarts to see that it is fact for a double.
 * airArray->len should probably be size_t, not unsigned int. Along with
 this is biffMsgErrNum and nrrdKeyValueSize.
 * consider changing airIndexULL and airIndexClampULL to work with
@@ -39,13 +59,11 @@
 * either change AIR_STRLEN_* to AIR_BUFFSIZE_* (or something similar,
 or take out the +1 from their definition and it into usage: the
 STRLEN is misleading as is.
-* important: change airArray implementation to re-allocate the array size
-multiplicatively (by some adjustable factor, default around 1.5 or 2.0),
-rather than the linear increments used now.  References:
-http://en.wikipedia.org/wiki/Dynamic_array
-http://hg.python.org/cpython/file/e3be2941c834/Objects/listobject.c
 * consider terminating airEnum->strEqv with NULL (just like argv)
 instead of with empty string ""
+* make airOneLine return number of bytes read; current return
+  of string length is entirely redundant with return of strlen()
+  and then enable the ftell() check after PNG magic read
 * reconcile names of "unsigned int airUIrandMT_r()" vs
   "unsigned int airRandInt()" and "unsigned int airRandInt_r()"
 * consider having something like a teemContext, which might be:
@@ -68,6 +86,23 @@
 things airType were created for the sake of hest. Instead of taking an
 airType enum value for hestOptAdd, hestOptAdd can take a string
 (e.g. "uchar", "float", "enum", "callback" for airTypeOther).
+* There's no such thing as a truly optional parameter: data is needed
+for all options, whether it comes from the default string or the
+command line, and its an error if no data is found.  Not having
+optional parameters is why things like "unu make" learn centerings via
+strings: the string can be given or not, and if its given, then the
+information is used.
+* There's no way to access the string that was parsed to get the
+information for an option (could be from default, or command-line,
+or response file)
+* (from tendGlyph.c): there needs to be an alternative API for hest
+that is not var-args based (as is hestOptAdd). You can't tell when
+you've based multiple strings for the detailed usage information by
+accident.  GLK had accidentally inserted a comma into my multi-line
+string for the "info" arg, relying on the automatic string
+concatenation, and ended up passing total garbage to hestOptAdd for
+the airEnum pointer, causing him to think that the tenGlyphType airEnum
+was malformed, when it was in fact fine ...
 
 biff:
 * biffMove(destKey, err, srcKey) --> biffMove(destKey, srcKey, err)
@@ -97,8 +132,15 @@
   just like nrrdDefaultWriteCharsPerLine and nrrdDefaultWriteValsPerLine)
   and argument to nrrdIoStateSet.
 * with NrrdKernel:
+ - debug apparent precision problems worked-around in nrrdKernelCheck
  - add fields for "what is my derivative" or "what is my integral", but
    how to do that at compile time?
+ - add field for "parm[0] controls the scaling that the old resampling code
+   (e.g. unu resample) has always assumed" vs "parm[0] isn't used".  The
+   assumption by the resampling code that all kernels use parm[0] was a big
+   longstanding bug; "bspln3" doesn't work that way
+ - consider nixing nrrdDefaultKernelParm0, nrrdEnvVarDefaultKernelParm0
+ - consider nixing nrrdDefaultSpacing and nrrdEnvVarDefaultSpacing
  - "when parsing from string, parm[0] is needed" vs "parm[0] defaults to 1.0"
    OR, maybe simplify things by saying that all parameters are always needed
  - add method for answering "do I interpolate?"
@@ -107,7 +149,6 @@
  - add: am I an odd or even function
  - rename numParm --> parmNum
  - fix the kernels that meetNrrdKernelAllCheck revealed to be broken
- - consider nixing nrrdDefaultKernelParm0, nrrdEnvVarDefaultKernelParm0
 * with NrrdFormat:
  - There is now an available() method, but this is incomplete - EPS is
    something that can be written for images, but not read in general.
@@ -117,8 +158,7 @@
    Is this something else that NrrdFormat should represent?
 * should re-evaluate the need for all the nrrdDefault and nrrdState
   global variables, especially nrrdStateGrayscaleImage3D,
-  nrrdEnvVarStateGrayscaleImage3D,
-  nrrdDefaultSpacing, nrrdEnvVarDefaultSpacing, which seem antiquated
+  nrrdEnvVarStateGrayscaleImage3D, which seem antiquated
 * the percentile-based bounds specification now supported in e.g
   "unu histo", "unu quantize", and "unu jhisto" should be migrated down
   to the nrrd library.  Consider doing this with a sorting of highest/lowest
@@ -143,27 +183,40 @@
 [nrrd] nrrdResampleKernelSet: haven't set input nrrd yet
 * for nrrdCropAuto: consider adding some minimum remaining size requirement,
   in addition to offset
-* all of the code in apply1D.c is ancient, and has not been brought into
-  the world of using unsigned int and size_t.  Also very confusing. Needs
-  to be walked through and tested thoroughly.
 * why is _nrrdCheck (different than nrrdCheck) public?  Should be renamed?
+* now that we the new NrrdBoundarySpec, it should be used, and used
+  consistently, throughout Teem; for example remove
+  nrrdResampleBoundarySet and nrrdResamplePadValueSet and instead use new
+  nrrdResampleBoundarySpecSet, and consider using NrrdBoundarySpec
+  inside of NrrdResampleContext
+* The guts of "unu make" have to be made into a function call.  Its crazy
+to have all those smarts not more generally available.
 
+
 unu:
 * the UNRRDU_QUIET_QUIT functionality should be enabled by default instead
-of having to set an environment variable to get it
+of having to set an environment variable to get it. Or maybe not: when this
+goes wrong it is REALLY mysterious, and hard to debug.  For example:
+"... | unu 2op x - 2 | ...".  If there is a directory named "2" in the
+current working directory, it will exist as a file, and hence be opened by
+unu as if it was a nrrd, but doing an fread on it will immediately hit EOF
+--> quiet quit, and very confusing.
 * unu dice -ff should change from using %d to %u
+* in unrrdu/make.c, reconsider the nrrdStateVerboseIO++ before, and the
+nrrdStateVerboseIO-- after, the calls to nrrdFormatNRRD->read.  You can
+set environment variable NRRD_STATE_VERBOSE_IO to 0 thinking this will turn
+things off, and yet its not off
 * unu resample:
--- should permit saying "resample this axis to whatever
-best preserves the aspect ratio relative to the one axis which is
-being resampled via the older "N" or "xF" means"
 -- consider supporting more sophisticated expressions e.g. "x2" --> "x2+1"
 -- reconsider whether normalization should be turned on by default
 (always a surprise when using purposely small kernels like cos4sup or
-small gauss)
+a small Gaussian)
 
 gage:
+* use new NrrdBoundarySpec whenever possible; for example remove
+gageStackBlurParmBoundarySet()
 * clean up gageVolumeCheck vs gageKindVolumeCheck mess
-* in a gageKinds, the airEnum for the items, and the assocaited table of
+* in a gageKinds, the airEnum for the items, and the associated table of
 pre-requisites, should really be compiled from some other description
 which is more reliably written and upated (updating a gageKind now is
 EXTREMELY error-prone).  More radically, perhaps the entire thing
@@ -186,16 +239,11 @@
 ** The items below have accumulated over time, but the importance of them
 ** for Teem 2.0 or any other release should be re-evaluated.
 
-large-scale fix: when using sizeof with memcpy or memset, should be using
-the variable name itself instead of type as argument to sizeof()
-
 for cmake:
  - build pv on windows
  - see if wild-card expansion works as expected on windows
  - make cmd-line utilities link with static libs
 
-unrrdu: standardize hest framework for doing unu/gkms/tend style programs
-
 [portable54-250:~/d/parepi/6] gk%
 tend estim -new -sigma 0.01 -est wls -i 6crop-dwi.nrrd \
    -B kvp -knownB0 false -t 250 -o tmp.nrrd
@@ -208,16 +256,8 @@
 
 gage: re-modularize to facilitate probing bricked data
 
-make system really botched: change the size of the tenFiberContext
-(added a field or two), do a make ten/install,
-then cd ../push; rm -f test/pusher
+bin/unu: valgrind parsing of encoding stuff
 
-air: make airOneLine return number of bytes read; current return
-  of string length is entirely redundant with return of strlen()
-  and then enable the ftell() check after PNG magic read
-
-bin/unu: valgrid parsing of encoding stuff
-
 gage changes into bane:
 - try gkms hvol with three explicit ranges
 - remove excess NULL pointer checks between answer and answer wrapper
@@ -229,12 +269,8 @@
 
 leaf: do it
 
-hest: add commenting via # or something else
-
 bane: finish updating tutorial
 
-dye: see if dyeColorParse should allocate the thing and return it
-
 image registration tool for small translational errors
 
 limn: make it smarter- so that joining parts together is possible in a
@@ -243,6 +279,8 @@
 
 limn: either debug or remove limnQN16border1
 
+dye: see if dyeColorParse should allocate the thing and return it
+
 dye: colormaps
 
 dye: hest callbacks
@@ -262,7 +300,13 @@
 callahan TVCG May/June 05: Hardware-Assisted Visibility Sorting for Unstructured Volume Rendering
 jorik blaas vis05 fiber paper
 
-(less of an issue now that CMake is in use) make install; make; and
+Following are less of an issue now that CMake is in use ...
+
+make system really botched: change the size of the tenFiberContext
+(added a field or two), do a make ten/install,
+then cd ../push; rm -f test/pusher
+
+make install; make; and
 you'll STILL get memory errors due to seeing library/object files
 which use the older context size.  Do a top-level make clobber, and
 then things work.  This is crap.  I think the problem is that

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.