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