-
Notifications
You must be signed in to change notification settings - Fork 10
a simple C interface for reading and writing small images in any format
License
mnhrdt/iio
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
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
About
a simple C interface for reading and writing small images in any format
Topics
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published