[Teem-commit] SF.net SVN: teem:[7432] teem/trunk/README.txt

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

Revision: 7432
          http://sourceforge.net/p/teem/code/7432
Author:   kindlmann
Date:     2025-09-14 22:53:00 +0000 (Sun, 14 Sep 2025)
Log Message:
-----------
updating anticipating Teem v2

Modified Paths:
--------------
    teem/trunk/README.txt

Modified: teem/trunk/README.txt
===================================================================
--- teem/trunk/README.txt	2025-09-14 22:09:05 UTC (rev 7431)
+++ teem/trunk/README.txt	2025-09-14 22:53:00 UTC (rev 7432)
@@ -1,25 +1,34 @@
 ===============
-  Teem: Tools to process and visualize scientific data and images
-  Copyright (C) 2009--2023  University of Chicago
-  Copyright (C) 2005--2008  Gordon Kindlmann
-  Copyright (C) 1998--2004  University of Utah
+Teem: Tools to process and visualize scientific data and images
+Copyright (C) 2009--2025  University of Chicago
+Copyright (C) 2005--2008  Gordon Kindlmann
+Copyright (C) 1998--2004  University of Utah
 
-  This library is free software; you can redistribute it and/or modify it under the terms
-  of the GNU Lesser General Public License (LGPL) as published by the Free Software
-  Foundation; either version 2.1 of the License, or (at your option) any later version.
-  The terms of redistributing and/or modifying this software also include exceptions to
-  the LGPL that facilitate static linking.
+This library is free software; you can redistribute it and/or modify it under the terms
+of the GNU Lesser General Public License (LGPL) as published by the Free Software
+Foundation; either version 2.1 of the License, or (at your option) any later version.
+The terms of redistributing and/or modifying this software also include exceptions to
+the LGPL that facilitate static linking.
 
-  This library is distributed in the hope that it will be useful, but WITHOUT ANY
-  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-  PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
-  You should have received a copy of the GNU Lesser General Public License
-  along with this library; if not, see <https://www.gnu.org/licenses/>.
+This library is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+You should have received a copy of the GNU Lesser General Public License
+along with this library; if not, see <https://www.gnu.org/licenses/>.
+
+=============== How to connect with other Teem users.
+
+In preparation for the Teem v2 release, there's a new Discord server:
+
+  https://discord.gg/xBBqZGXkF7
+
+Join!
+
 =============== License information
 
-See above.  This preamble should appear on all released files. Full text of the
-Simple Library Usage License (SLUL) should be in the file "LICENSE.txt".  The
-SLUL is the GNU Lesser General Public License, plus an exception:
+See above.  This preamble should appear on all released source files. Full text
+of the Simple Library Usage License (SLUL) should be in the file "LICENSE.txt".
+The SLUL is the GNU Lesser General Public License v2.1, plus an exception:
 statically-linked binaries that link with Teem can be destributed under the
 terms of your choice, with very modest provisions.
 
@@ -33,25 +42,45 @@
 (with static-linking):
 
   svn co https://svn.code.sf.net/p/teem/code/teem/trunk teem-src
-  mkdir teem-build
-  cd teem-build
+  TEEM_SRC=$(cd teem-src && pwd)
+  TEEM_INSTALL=$(mkdir teem-install && cd teem-install && pwd)
+  mkdir teem-build && cd teem-build
   cmake \
-    -D BUILD_SHARED_LIBS=OFF -D BUILD_TESTING=OFF \
+    -D BUILD_SHARED_LIBS=ON -D BUILD_TESTING=OFF \
     -D CMAKE_BUILD_TYPE=Release \
-    -D Teem_BZIP2=OFF -D Teem_FFTW3=OFF -D Teem_LEVMAR=OFF -D Teem_PTHREAD=OFF \
-    -D Teem_PNG=ON -D Teem_ZLIB=ON \
-    -D CMAKE_INSTALL_PREFIX:PATH=../teem-install \
+    -D Teem_USE_FFTW3=OFF -D Teem_USE_LEVMAR=OFF \
+    -D Teem_USE_BZIP2=ON -D Teem_USE_PNG=ON \
+    -D Teem_USE_ZLIB=ON -D Teem_USE_PTHREAD=ON \
+    -D CMAKE_INSTALL_PREFIX=$TEEM_INSTALL \
     ../teem-src
   make install
 
-Use BUILD_SHARED_LIBS=ON to make a libteem shared library, which is the
-basis of the python wrappers (e.g. teem/python/cffi)
+If you're squeamish about your command-line tools relying on shared libraries,
+use BUILD_SHARED_LIBS=OFF. btw Teem's CMake sets the rpath in the command-line
+tools to be relative, so the install directory can be moved elsewhere, as long
+as the `bin` and `lib` directories stay side-by-side.
 
+Using BUILD_SHARED_LIBS=ON makes a libteem shared library, which enables the
+python/CFFI wrapping, which you do with this (with a python3 that can
+"import cffi"):
+
+  cd $TEEM_SRC/python/cffi && python3 build_teem.py $TEEM_INSTALL
+
+Then you can, in python3:
+
+  import teem
+
+and have fast compiled access to the entire Teem API, with biff error messages
+turned into Python exceptions.
+
 =============== Directory Structure
 
+* CMake/
+  Files related to compiling Teem with CMake
+
 * src/
-  With one subdirectory for each of the teem libraries, all the
-  source for the libraries is in here.  See library listing below.
+  With one subdirectory for each of the teem libraries (air, biff, hest, nrrd, etc);
+  All the source for the libraries is in here.  See library listing below.
   The src/CODING.txt file documents Teem coding conventions.
   * src/make
     Files related to compiling Teem with src/GNUmakefile, the old way
@@ -59,56 +88,55 @@
   * src/bin
     Source files for Teem command-line tools, including "unu" and "tend"
 
+* UseTeemCMakeDemo/
+  An stand-alone example of how to use the Teem::Teem package, created by CMake
+  (via the new CMake files re-written Sept 2025)
+
 * include/
   Some short header files that are used to check the setting of compiler
-  variables
-  * include/teem/
-    When using the old GNU make system, the include (.h) files for all the
-    libraries (such as nrrd.h) get put here (but don't originate here).
+  variables while building Teem, but not used by any downstream user.
+  Currently just teemPng.h, which ensures that support for zlib compression
+  is being compiled in if png format is being compiled in.
 
-* CMake/
-  Files related to compiling Teem with CMake
+* python/
+  For python wrappings
+  * python/cffi
+    Bindings for python via CFFI, for all of Teem (in teem.py), as well as a
+    way (exult.py) to create bindings for other C libraries that depend on Teem
+    (created in August 2022)
+  * python/ctypes
+    Bindings for python via ctypes; currently out of date because it
+    depended on the moribund gccxml
 
-* Testing/
-  Tests run by CTest.  More should be added.
-
-* data/
-  Small reference datasets; more may be added for testing
-
 * built/
-  The old GNU make system (non-CMake) puts things here:
+  The non-CMake GNUmake system puts things here:
   * include/
     the headers
   * lib/
-    all libraries put both their static/archive (.a) and
-    shared/dynamic (.so) library files here (such as libnrrd.a)
+    all libraries put their static/archive (.a) ibrary files here
   * bin/
-    all libraries put their binaries here, hopefully in a way which
-    doesn't cause name clashes
+    all command-line tools (like unu) go here
   * obj/
-    make puts all the .o files in here, for all libraries. When
-    compiling "dev", it also puts libraries here, so that "tests"
-    can link against them there
+    make puts all the .o files in here, for all libraries, hopefully with no
+    name clashes.
 
-* python/
-  For python wrappings
-  * python/cffi
-    Bindings for python via CFFI, for all of Teem (in teem.py), as well
-    as a way (exult.py) to create bindings for other C libraries that
-    depend on Teem (created in August 2022)
-  * python/ctypes
-    Bindings for python via ctypes; currently out of date because it
-    depended on the moribund gccxml
+* tests/
+  * ctest/
+    Tests run by CTest.  More should be added.
+  * python/
+    Future home of tests that access Teem via Python/CFFI bindings
 
-* Examples/
-  Place for examples of Teem-using programs, but unfortunately
-  not populated by much right now.  A work in progress.
+* data/
+  Small reference datasets; more may be added for testing
 
+* matlab/
+  Matlab bindings written in 2005, not touched since then; do they still work?
+
 =============== Teem libraries
 
-Teem is a coordinated collection of libraries, with a stable
-dependency graph.  Below is a listing of the libraries (with
-indication of the libraries upon which it depends).  (TEEM_LIB_LIST)
+Teem is a coordinated collection of libraries, with a stable dependency graph.
+Below is a listing of the libraries (with indication of the libraries upon
+which it depends).  (TEEM_LIB_LIST)
 
 * air: Basic utility functions, used throughout Teem
 
@@ -116,24 +144,24 @@
 
 * 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)
+* nrrd: Nearly Raw Raster Data- library for raster data manipulation, 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)
+* ell: Linear algebra: operations on vectors, matrices and quaternions, and
+solving cubic polynomials. (nrrd, biff, air)
 
 * moss: Processing of 2D multi-channel images (ell, nrrd, biff, hest, air)
 
-* unrrdu: internals of "unu" command-line tool, and some machinery used
-in other multi-command tools (like "tend") (moss, nrrd, biff, hest, air)
-"unu ilk" is new home for "ilk" image transformer built on moss
+* unrrdu: internals of "unu" command-line tool, and some machinery used in
+other multi-command tools (like "tend") (moss, nrrd, biff, hest, air). "unu
+ilk" is new home for "ilk" image transformer built on moss
 
 * alan: Reaction-diffusion textures (nrrd, ell, biff, air)
 
 * tijk: Spherical harmonics and higher-order tensors (ell, nrrd, air)
 
-* gage: Convolution-based measurement of 3D fields, or 4D scale-space
-(ell, nrrd, biff, air)
+* gage: Convolution-based measurement of 3D fields, or 4D scale-space (ell,
+nrrd, biff, air)
 
 * dye: Color spaces and conversion (ell, biff, air)
 
@@ -141,18 +169,18 @@
 (gage, unrrdu, nrrd, biff, air)
 
 * limn: Basics of computer graphics, including polygonal data representation
-and manipulation (gage, ell, unrrdu, nrrd, biff, hest, air)
+and manipulation (ell, unrrdu, nrrd, biff, hest, air)
 
 * echo: Simple ray-tracer, written for class (limn, ell, nrrd, biff, air)
 
-* hoover: Framework for multi-thread ray-casting volume renderer
-(limn, ell, nrrd, biff, air)
+* hoover: Framework for multi-thread ray-casting volume renderer (limn, ell,
+nrrd, biff, air)
 
-* seek: Extraction of polygonal features from volume data, including
-Marching Cubes and ridge surfaces (limn, gage, ell, nrrd, biff, hest, air)
+* seek: Extraction of polygonal features from volume data, including Marching
+Cubes and ridge surfaces (limn, gage, ell, nrrd, biff, hest, air)
 
 * ten: Visualization and analysis of diffusion imaging and diffusion tensor
-fields (echo, limn, dye, gage, unrrdu, ell, nrrd, biff, air)
+fields (echo, limn, gage, unrrdu, ell, nrrd, biff, air)
 
 * elf: Visualization/processing of high-angular resolution diffusion imaging
 (ten, tijk, limn, ell, nrrd, air)
@@ -162,26 +190,29 @@
 
 * coil: Non-linear image filtering (ten, ell, nrrd, biff, air)
 
-* push: Original implmentation of glyph packing for DTI
-(ten, gage, ell, nrrd, biff, air)
+* push: Original implmentation of glyph packing for DTI (ten, gage, ell, nrrd,
+biff, air)
 
-* mite: Hoover-based volume rendering with gage-based transfer functions
-(ten, hoover, limn, gage, ell, nrrd, biff, air)
+* 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
-(mite, push, coil, pull, elf, ten, seek, hoover, echo, limn, bane, dye,
-gage, tijk, moss, alan, unrrdu, ell, nrrd, biff, hest, air)
+* 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)
 
 =============== Teem comand-line tools
 
-The easiest way to access the functionality in Teem is with its
-command-line tools.  Originally intended only as demos for the Teem
-libraries and using their APIs, the command-line tools have become a
-significant way of getting real work done.  Source for the tools is in
-teem/src/bin.  The most commonly used tools are:
+The easiest way to access the functionality in Teem is with its command-line
+tools.  Originally intended only as demos for the Teem libraries and using
+their APIs, the command-line tools have become a significant way of getting
+real work done.  Source for the tools is in teem/src/bin.  The most commonly
+used tools are:
 
-* unu: uses the "nrrd" library; a fast way to do raster data processing
-and visualization
+* unu: uses the "nrrd" library; a fast way to do raster data processing and
+visualization. What the rest of the world does in numpy, you maybe able to do
+on the command-line with unu. Type "unu" to see the commands; type "unu all" to
+see extra hidden commands (like "unu undos" for converting text files from
+Windows to normal)
 
 * tend: uses the "ten" library; for DW-MRI and DTI processing
 

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