forked from mnhrdt/iio
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
412 lines (279 loc) · 12.6 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
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
IIO
===
1. OVERVIEW
-----------
This is a collection of C functions (not a library), for reading small images
in many formats.
To use the functions, copy the "iio.c" and "iio.h" files into your source code.
Edit the macros at the start of "iio.c" to fine-tune your library requirements.
Find bindings for lua, octave and python inside the "interfaces" folder.
The Python binding can be installed by "pip install iio".
Find several usage examples in the imscript suite: git.sr.ht/~coco/imscript
2. PHILOSOPHY
-------------
An image is an array of numbers. Not intensities, not luminances, just
numbers. The iio functions allow you to read these numbers from files.
If the file contains the number 7, then iio will give you 7. All metadata
regarding the meaning and scaling of these numbers is energically ignored.
Images are always read as a whole, and are copied several times internally.
Thus IIO is only suitable for reading small images. If you need to read small
portions of large images in an efficient way, take a look at "fancy_image.c"
As a matter of principle, no image processing is ever done by iio.
2. BASIC USAGE
--------------
Read the pixels of "lena.png" into an array of floats:
int w, h, pd; // image width, heigth, pixel dimension
float *x = iio_read_image_float_vec("lena.png", &w, &h, &pd);
Write an array of WxHxD floats into file "out.tif":
iio_write_image_float_vec("out.tif", x, W, H, D);
When reading an image, the filename extension is ignored.
When writing an image, the extension is used to select the file format.
Reading from the image "-" is equivalent to reading from standard input.
Writing into the image "-" is equivalent to writing to standard output.
2.1. OTHER LANGUAGES
The bindings for other languages strive to be the most natural possible.
Sometimes the numbers are force converted to floats.
# octave
x = iio_read('lena.png')
iio_write('neg_lena.png', 255-x)
-- luajit
x = iio_read("lena.png") -- x has fields .w .h .pd .x
iio_write("lena.png", x)
-- lua
local iio = require("imgiio")
x = iio.read("lena.png") -- x has the same fields, and is callable as x(i,j)
iio.write("lena.png", x)
# python
import iio
x = iio.read("lena.png") # x is a numpy array
iio.write("neg_lena.png", 255-x)
# jupyter notebooks and sixel-terminals
iio.display(x)
iio.gallery([x, y, z])
3. ADVANCED USAGE
-----------------
3.1. ALTERNATIVE PIXEL ORDERING ( RGBRGBRGB... vs. RRR...GGG...BBB... )
An image is an array of pixels, and each pixel is an array of samples.
This means that for a typical RGB image the numbers are stored as RGBRGBRGB...
If you want RRRRR...GGGG...BBBB... you do not want an image, but an array of
images, where the components of each pixel have been broken into separate
images. Then you use the "_split" functions instead of the "_vec" functions
from iio.
Read "lena.png" into three contiguous images with the R,G,B components of each
pixel:
int w, h, pd; // image width, heigth, pixel dimension
float *x = iio_read_image_float_split("lena.png", &w, &h, &pd);
3.2. GRAY IMAGES
If you want to work with gray images (e.g., one-dimensional pixels), there are
functions where pd=1 is implicit. The following code reads a gray-level lena:
int w, h; // image width, height
float *x = iio_read_image_float("lena.png", &w, &h);
3.3. OTHER DATA TYPES
The recommended data type for iio is "float". However, the other C types are
possible. For example, the following code quantizes an image to 8 bits
// quantize a floating-point tiff into a 8-bit png
int w, h;
uint8_t *x = iio_read_image_uint8("in.tiff", &w, &h);
iio_write_image_uint8("out.png", x, w, h);
Notice that, since IIO does not do image processing, the quantized values are
not scaled. In this example, if "in.tiff" had floating-point values between 0
and 1, then "out.png" will be identically zero. If you want any kind of value
scaling you have to do it yourself:
// quantize a floating-point tiff into a 8-bit png
int w, h;
float *x = iio_read_image_float("in.tiff", &w, &h);
uint8_t *y = malloc(w*h);
for (int i = 0; i < w*h; i++)
y[i] = 255 * x[i];
iio_write_image_uint8("out.png", y, w, h);
When converting floats into ints, numeric values outside the range of the int
are clipped, and NANs are converted to 0.
4. MAGIC USAGE
--------------
4.1. MAGIC FILENAMES
Some strings are recognized by IIO as "magic" filenames
"-" standard input (when reading)
"-" standard output (when writing)
"zero:512x512" a zero gray image of the indicated size
"zero:512x512x3" a zero color image of the indicated size
"one:WxH" an image of ones
"constant:17:256x256" a constant gray image = 17
"constant:nan:256x256x3" a rgb image full of NANs
"http://URL" dowload the image using wget and load it
4.2. MAGIC ACCESSORS
The different parts of a multi-part TIFF image can be accessed by a suffix:
"file.tiff" read the first image in the file
"file.tiff,0" equivalent to "file.tiff"
"file.tiff,3" read the fourth image in the file
Similarly, for the different (named) datasets in an HDF5 image:
"file.nc" read the "/dset" dataset (unlikely to exist)
"file.nc,/PROD/radiance" read the named dataset
4.3. RAW IMAGES
Idea: to read a raw file named "file.xxx", open the image
with name "RAW[...]:file.xxx". The "..." specify the
details of the raw format.
Example:
RAW[w320,h200,tFLOAT]:file.xxx
This reads 320x200 floats from "file.xxx".
The contents of [ ] are a list of "tokens", separated by ","
Each token is a character followed by its value
Valid characters with their meaning:
w = width
h = height
p = pixel dimension (e.g. 1 or 3)
t = one of "INT8", "UINT8", "INT16", "UINT16", "INT32", "UINT32",
"INT64", "UINT64", "FLOAT", "DOUBLE", "LONGDOUBLE", "HALF", "UINT1",
"UINT2", "UINT4", "CHAR", "SHORT", "INT", "LONG", "LONGLONG",
o = offset bytes to be ignored from the start of the file
(if negative, ignored from the byte after th end of the file)
((default=-1 == EOF))
b = 0,1 wether pixel channels are contiguous or broken into planes
e = 0,1 controls the endianness. By default, the native one
r = xy, xY, Xy, XY, yx, Yx, yX, YX
controls the orientation of the coordinates (uppercase=reverse)
All the numeric fields can be read from the same file. For example,
"w@44/2" says that the width is read from position 44 of the file
as an uint16, etc.
More magic: Specifying the RAW type using environment variables.
Typically, when IIO fails to recognize the filetype, it tries some desperate
measures. One of this desperate measures is enabled by the environment
variable IIO_RAW, that specifies the "rawstring" of the file to be opened.
4.4. IMAGE COMMENTS
As a matter of principle, any kind of image metadata is severely frowned upon.
Still, iio provides limited support for adding metadata to image files at the
moment of writing them. Only "comment" metadata fields are allowed, and only
for four file formats: png, jpeg, tiff and ppm.
Metadata comments are specified by the REM prefix when calling iio_write_*.
For example, writing a file with this name:
REM[abc]:file.png
Will write an image "file.png" with the comment "abc" inside.
Equivalently, you can also set the environment variable IIO_REM=abc to the same
effect.
5. BLACK MAGIC USAGE
--------------------
The suffix "TRANS" allows to apply some transformations to images after being
read. For example
TRANS[x=10]:file.png trim the first 10 columns of the image
TRANS[y=10]:file.png trim the first 10 lines of the image
TRANS[w=100]:file.png force the image to have width 100
TRANS[h=100]:file.png force the image to have height 100
TRANS[y=10,h=100]:file.png extract lines 10...110
TRANS[h=100,y=10]:file.png extract lines 10...90
TRANS[flip=topdown]:file.png flip the image top down
Notice that arguments of TRANS are comma-separated and applied sequentially.
Besides "topdown", the "flip" transform admits the following arguments, with
obvious meanings.
identity
leftright
topdown
transpose
posetrans
r90
r270
r180
There is a further, very dangerous, argument of TRANS that is named "pipe". It
pipes image through the indicated shell command.
TRANS[pipe="qauto -i"]:file.png
Normalize the colors of the image
TRANS[pipe="plambda 'split rot rgb'|qauto -i"]:file.png
Swap the blue and green channels, and normalize
TRANS[pipe="plambda split_rot_rgb|qauto -i"]:file.png
Same as before, but easier to escape
Even worse (!): You can define an environment variable "IIO_TRANS" and the
transformation will be applied to *all* iio-using programs that see the
environement variable. For example, if you have a folder with a lot of images,
you can browse their fft using pvflip as follows:
IIO_TRANS="pipe=fft|plambda vnorm_1_+_log" pvflip *.png
That's enough black magic for now, but rest assured that there's more.
6. COMPILE TIME CONFIGURATION
-----------------------------
The visible interface to iio is defined on file "iio.h" and it does not change.
However, the set of recognized image formats can be chosen at compile time,
either by manually editing the file "iio.c" or by setting preprocessor
variables.
The simplest setting is to disable all library requirements so that iio only
deals with simple uncompressed formats like pgm and npy. For that, uncomment
the line that defines IIO_DISABLE_IMGLIBS at the start of iio.c. Equivalently,
you can pass this definition as a preprocessor option: -DIIO_DISABLE_IMGLIBS
//#define IIO_SHOW_DEBUG_MESSAGES
//
// Wether you want to be extremely verbose (useful for debugging only)
//#define IIO_ABORT_ON_ERROR
//
// Whether to ABORT the program on error instead of returning NULL.
//#define IIO_DISABLE_IMGLIBS
//
// Disable all readers requiring external libraries.
You can also select a particular set of libraries from the compiler command
line. For example, the options "-DI_CAN_HAS_LIBTIFF -DDISABLE_LIBPNG" enables
TIFF and disables PNG.
7. SUPPORTED FORMATS FOR READING
--------------------------------
The following image formats can be read natively, regardless of the
compile-time options:
* PNM (any format recognized by netpbm)
* NUMPY (python's numpy arrays)
* RIM (megawave's image format)
* ASC (cimg general 4d arrays)
* PFM (portable floatmap)
* QNM (a straightforward generalization of PNM)
* CSV (a csv array is read into a gray image)
* VRT (gdal's virtual images)
* PCM (for optical flows and complex images)
* FLO (for middlebury optical flows)
* JUV (optical flows)
* LUM ("luminance" images)
* FARBFELD (suckless 16bit photo format)
* PDS (Planetary Data System)
* VICAR (astronomical images)
* CCSD3ZF (PDS with a different magic number)
* FITS (astronomical images)
* raw uncompressed image data (see section 4 "MAGIC USAGE" above)
The following formats can be read using external library support (when the
appropriate compile-time option is enabled):
* PNG
* JPEG
* TIFF
* WEBP (disabled by default, for now)
* HEIF (disabled by default)
* EXR (disabled by default, shenanigans on some bsd distros)
* HDF5 (disabled by default, huge dependency)
8. SUPPORTED FORMATS FOR WRITING
--------------------------------
Although the main concern of IIO is to READ images, the library
provides some convenience functions for writing images. This is a
secondary afterthought, and there is no intention to support a
complete set of formats. Specifically, lossy compression is not
implemented.
By default, images are now saved as (uncompressed) numpy arrays. If a file
extension is recognized then a different format is used:
.npy : Numpy array
.asc : Cimg's 4-dimensional array
.mw : Megawave's RIM files
.pgm : portable graymap
.ppm : portable pixmap
.pfm : portable floatmap
.csv : comma-separated values printed in ascii
.flo : a middlebury optical flow
.uv : javier's optical flow format
.six : sixels (useful for plotting into xterm)
.tif :
.tiff :
.TIF :
.TIFF : tiff format (type is determined by C data type)
.png :
.PNG : png format (8 bits)
To force TIFF output format, prefix the filename with "TIFF:". For example,
"TIFF:-" writes a TIFF file to stdout.
To force 16 bits png, use the prefix "PNG16:".
8. FILES
--------
iio.h interface (main source of documentation)
iio.c implementation
doc/* documentation (mostly philosohpical)
samples/* test images
mini/iio.{c,h} mini version, crippled, without deps
interfaces/octave/* octave bindings
interfaces/lua/* lua bindings
interfaces/python/* python bindings
interfaces/cmake/* cmake helper files