"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/tkimg/README" (13 Nov 2019, 8731 Bytes) of package /linux/misc/ds9.8.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 
    2         Tcl/Tk Image formats (TkImg)
    3         (Version 1.4.9 / MArch 2019)
    4 
    5         Jan Nijtmans, Andreas Kupries, Paul Obermeier
    6 
    7 This file contains a collection of format handlers for the Tk photo
    8 image type, and a new image type, pixmaps.  It can be used in
    9 combination with Tcl/Tk 8.3 or later but 8.6 or newer are highly
   10 recommended.
   11 
   12 Included in this distribution are the most recent versions (as of
   13 March 2019) of the libz, libpng, libjpeg, and libtiff libraries.
   14 These are not required, unless you need support for the PNG, JPEG,
   15 or TIFF format. Note that you have to build these libraries to
   16 support the named formats, even if your system already has shared
   17 libraries for these formats. This is because the libraries here are
   18 built such that they can be loaded as packages by the Tcl/Tk core,
   19 making the handling of the various dependencies much easier. An
   20 earlier version, 1.2.4, used a modified copy of Tcl's functions for
   21 loading of shared libraries to load the support libraries at runtime.
   22 These have been abandoned in favor of the new approach.
   23 
   24 BACKGROUND TO BUILDING
   25 
   26 The TkImg sources have been heavily refactored. Instead of building
   27 one big package there are several small packages most of which are
   28 independent of each other.
   29 
   30 All packages employ a TEA based build system (configure/make) for
   31 easy configuration and building. This means that 99% of the options
   32 to configure are the same for all the packages.
   33 
   34 All packages save for the supporting ones (see below) have names
   35 starting with 'img'. For compatibility with older scripts the
   36 package index file of the utility package 'img::base' declares
   37 pseudo-packages 'img' and 'Img' which load all packages provided
   38 by this extension with the exception of formats raw, flir and dted.
   39 See below for details on these packages.
   40 
   41 BUILDING - The convenient way
   42 
   43 The toplevel directory of tkImg contains a configure and Makefile for
   44 convenient configuration and building of all packages in the
   45 extension.
   46 
   47 Run this configure script in a build directory of your choice to
   48 configure all packages, then run
   49 
   50     make all
   51     make install
   52 
   53 in the build directory. The most important options for configure are
   54 --prefix and --exec-prefix which tell the build system where to find
   55 Tcl and Tk, and also where to install the results of the builds
   56 (header, shared libraries, ...).
   57 
   58 This convenient build installs all shared libraries in a single
   59 directory 'Img<VERSION>, together with a union package index for all
   60 packages.
   61 
   62 If the builder requires only a subset of the packages he can use
   63 
   64     make all
   65 
   66 to build all packages, but must not use 'make install' in the top
   67 build directory. Instead run
   68 
   69     make install
   70 
   71 in the sub directories of the build directory which contain the
   72 requested packages, and their dependencies !
   73 
   74 Note, that target install also builds the documentation based on 
   75 Tcl script dtplite. To build and install without documentation, use
   76 
   77     make install-libraries
   78 
   79 PACKAGES AND THEIR DEPENDENCIES
   80 
   81 This section is for people who want to bypass the master
   82 configure/Makefile.
   83 
   84 At the bottom of the hierarchy of dependencies are the 'support
   85 packages'. They encapsulate the support libraries for ZIP, TIFF, PNG
   86 and JPEG in packages directly loadable by Tcl. They provide the
   87 functionality of their underlying libraries via stub-tables. The names
   88 of these packages are:
   89 
   90     Name        Directory           Dependency
   91     -------------------------------------------------
   92     zlibtcl     tkimg/compat/libz
   93     pngtcl      tkimg/compat/libpng   zlibtcl
   94     jpegtcl     tkimg/compat/libjpeg
   95     tifftcl     tkimg/compat/libtiff
   96     -------------------------------------------------
   97 
   98 The package 'pngtcl' depends on 'zlibtcl' and has to be built after
   99 it. Beyond that the order of building is free. Their TEA build systems
  100 can be found in the directories listed above.
  101 
  102 The configure/Makefile's in the directories
  103 
  104     tkimg/compat/libz
  105     tkimg/compat/libpng
  106     tkimg/compat/libjpeg
  107     tkimg/compat/libtiff
  108 
  109 must _not_ be used directly under any circumstances.
  110 
  111 
  112 At the next level is the package 'tkimg'. It provides utility
  113 functions used by all format handlers, and therefore has to be built
  114 before any of them. Its TEA build system can be found in the directory
  115 
  116     Name        Directory       Dependency
  117     -------------------------------------------------
  118     img::base   tkimg/base
  119     -------------------------------------------------
  120 
  121 Beyond that are the packages providing the various format
  122 handlers. They can be built in any order. Some of them depend on
  123 supporting packages, as noted below. Their names and directories are
  124 
  125     Name        Directory   Dependency
  126     -------------------------------------------------
  127     img::bmp    tkimg/bmp
  128     img::gif    tkimg/gif
  129     img::ico    tkimg/ico
  130     img::jpeg   tkimg/jpeg  jpegtcl
  131     img::pcx    tkimg/pcx
  132     img::pixmap tkimg/pixmap
  133     img::png    tkimg/png   pngtcl, zlibtcl
  134     img::ppm    tkimg/ppm
  135     img::ps     tkimg/ps
  136     img::sgi    tkimg/sgi
  137     img::sun    tkimg/sun
  138     img::tga    tkimg/tga
  139     img::tiff   tkimg/tiff  tifftcl, zlibtcl, jpegtcl
  140     img::window tkimg/window
  141     img::xbm    tkimg/xbm
  142     img::xpm    tkimg/xpm
  143 
  144     img::dted   tkimg/dted
  145     img::flir   tkimg/flir
  146     img::raw    tkimg/raw
  147     -------------------------------------------------
  148 
  149 The packages img::dted, img::flir and img::raw are special, because they are
  150 not included when doing a "package require Img". These must be explicitely
  151 loaded via a "package require img::FMT".
  152 img::dted reads Digital Terrain Elevation Data and transforms the elevation
  153 data into photo images.
  154 img::flir reads FLIR files and transforms the temperature information 
  155 into photo images.
  156 img::raw can transform any form of binary matrix data
  157 (8-bit and 16-bit integer, 32-bit float) into a photo image.
  158 As DTED and RAW files do not have a magic key or other identifier at the beginning
  159 of the file, it is not possible to automatically detect the format by reading
  160 some file header.
  161  
  162 CONFIGURE
  163 
  164 The source distributions have "configure", which  has the following
  165 possibilities:
  166     configure ?options?
  167 
  168 Some possible options:
  169     --prefix=<dir>      Install headers in <dir>/include.
  170                 Default: "/usr/local"
  171     --exec-prefix=<dir> Install libraries in <dir>/lib.
  172                 Default: "${prefix}"
  173     --with-tcl=<dir>    Find Tcl libraries in <dir> and include files in
  174                 <dir>/../include or <dir>/../generic.
  175                 Default: "${exec-prefix}/lib" or a sibling directory
  176                 of the Img build directory.
  177     --with-tk=<dir>     Find Tk libraries in <dir> and include files in
  178                 <dir>/../include or <dir>/../generic.
  179                 Default: the same values as given by --with-tcl
  180                 or a sibling directory of the Img build directory.
  181 
  182     Packages dependent on one or more of the support packages have
  183     appropriate options to locate their libraries and headers, if
  184     they cannot be found via --prefix and --exec-prefix
  185 
  186     Use configure --help to query each configure for the full set
  187     of options available to it.
  188 
  189 
  190 MAKE & INSTALL
  191 
  192     'make', or 'make all' will build any package.
  193 
  194     'make install' will install its headers and libraries in the
  195     directories specified via --prefix/include and --exec-prefix/lib.
  196 
  197 USE
  198 
  199 If you want to use one or more of new image formats to be available in
  200 your own scripts, add a line like the following somewhere in your
  201 script:
  202 
  203     package require img::FORMAT
  204 
  205 where FORMAT stands for the name of the format requested. See the list
  206 in section 'PACKAGES AND THEIR DEPENDENCIES' for the available
  207 formats. Each format will automatically load all of the packages it is
  208 dependent on.
  209 
  210 The line
  211     package require Img
  212 
  213 is still legal and will load all format handlers provided by this
  214 extension except dted, flir and raw.
  215 
  216 As an example, have a look at the file "demo.tcl"
  217 
  218 For further options see the manpages.
  219 
  220 
  221 DOCUMENTATION
  222 
  223 The documentation coming with the distribution is written in the
  224 doctools format (see tcllib).
  225 
  226 PLATFORMS
  227     Tested:
  228         Linux    (gcc)
  229         Windows  (MSys/MinGW, Visual Studio C++)
  230         Darwin   (gcc)
  231 
  232     Other machines and OS's should work too. 
  233 
  234 Feedback about other OS's and compilers is appreciated. Please
  235 help us in making this package better.
  236 
  237 Jan Nijtmans    (nijtmans@users.sourceforge.net)
  238 Andreas Kupries (andreas_kupries@users.sourceforge.net)
  239 Paul Obermeier  (obermeier@users.sourceforge.net)