Leptonica  1.83.1
Image processing and image analysis suite
pix_internal.h File Reference

Go to the source code of this file.

Data Structures

struct  Pix
 
struct  PixColormap
 
struct  RGBA_Quad
 
struct  Pixa
 
struct  Pixaa
 
struct  Box
 
struct  Boxa
 
struct  Boxaa
 
struct  Pta
 
struct  Ptaa
 
struct  Pixacc
 
struct  PixTiling
 
struct  FPix
 
struct  FPixa
 
struct  DPix
 
struct  PixComp
 
struct  PixaComp
 

Macros

#define PIXAA_VERSION_NUMBER   2
 
#define PIXA_VERSION_NUMBER   2
 
#define BOXA_VERSION_NUMBER   2
 
#define BOXAA_VERSION_NUMBER   3
 
#define PTA_VERSION_NUMBER   1
 
#define FPIX_VERSION_NUMBER   2
 
#define DPIX_VERSION_NUMBER   2
 
#define PIXACOMP_VERSION_NUMBER   2
 

Detailed Description

Valid image types in leptonica: Pix: 1 bpp, with and without colormap Pix: 2 bpp, with and without colormap Pix: 4 bpp, with and without colormap Pix: 8 bpp, with and without colormap Pix: 16 bpp (1 spp) Pix: 32 bpp (rgb, 3 spp) Pix: 32 bpp (rgba, 4 spp) FPix: 32 bpp float DPix: 64 bpp double Notes: (1) The only valid Pix image type with alpha is rgba. In particular, the alpha component is not used in cmapped images. (2) PixComp can hold any Pix with IFF_PNG encoding. This file is internal: it is not part of the public interface. It contains the definitions of most of the image-related structs used in leptonica: struct Pix struct PixColormap struct RGBA_Quad struct Pixa struct Pixaa struct Box struct Boxa struct Boxaa struct Pta struct Ptaa struct Pixacc struct PixTiling struct FPix struct FPixa struct DPix struct PixComp struct PixaComp This file can be #included after allheaders.h in source files that require direct access to the internal data fields in these structs. Notes on the pixels in the raster image. Most of this information can also be found in pix.h. (1) The image data is stored in a single contiguous array of l_uint32, into which the pixels are packed. By "packed" we mean that there are no unused bits between pixels, except for end-of-line padding to satisfy item (2) below. (2) Every image raster line begins on a 32-bit word boundary within this array. (3) Pix image data is stored in 32-bit units, with the pixels ordered from left to right in the image being stored in order from the MSB to LSB within the word, for both big-endian and little-endian machines. This is the natural ordering for big-endian machines, as successive bytes are stored and fetched progressively to the right. However, for little-endians, when storing we re-order the bytes from this byte stream order, and reshuffle again for byte access on 32-bit entities. So if the bytes come in sequence from left to right, we store them on little-endians in byte order: 3 2 1 0 7 6 5 4 ... This MSB to LSB ordering allows left and right shift operations on 32 bit words to move the pixels properly. (4) We use 32 bit pixels for both RGB and RGBA color images. The A (alpha) byte is ignored in most leptonica functions operating on color images. Within each 4 byte pixel, the color samples are ordered from MSB to LSB, as follows: | MSB | 2nd MSB | 3rd MSB | LSB | red green blue alpha 0 1 2 3 (big-endian) 3 2 1 0 (little-endian) Because we use MSB to LSB ordering within the 32-bit word, the individual 8-bit samples can be accessed with GET_DATA_BYTE and SET_DATA_BYTE macros, using the (implicitly big-ending) ordering red: byte 0 (MSB) green: byte 1 (2nd MSB) blue: byte 2 (3rd MSB) alpha: byte 3 (LSB) The specific color assignment is made in this file, through the definitions of COLOR_RED, etc. Then the R, G B and A sample values can be retrieved using redval = GET_DATA_BYTE(&pixel, COLOR_RED); greenval = GET_DATA_BYTE(&pixel, COLOR_GREEN); blueval = GET_DATA_BYTE(&pixel, COLOR_BLUE); alphaval = GET_DATA_BYTE(&pixel, L_ALPHA_CHANNEL); and they can be set with SET_DATA_BYTE(&pixel, COLOR_RED, redval); SET_DATA_BYTE(&pixel, COLOR_GREEN, greenval); SET_DATA_BYTE(&pixel, COLOR_BLUE, blueval); SET_DATA_BYTE(&pixel, L_ALPHA_CHANNEL, alphaval); More efficiently, these components can be extracted directly by shifting and masking, explicitly using the values in L_RED_SHIFT, etc.: (pixel32 >> L_RED_SHIFT) & 0xff; (red) (pixel32 >> L_GREEN_SHIFT) & 0xff; (green) (pixel32 >> L_BLUE_SHIFT) & 0xff; (blue) (pixel32 >> L_ALPHA_SHIFT) & 0xff; (alpha) The functions extractRGBValues() and extractRGBAValues() are provided to do this. Likewise, the pixels can be set directly by shifting, using composeRGBPixel() and composeRGBAPixel(). All these operations work properly on both big- and little-endians. (5) A reference count is held within each pix, giving the number of ptrs to the pix. When a pixClone() call is made, the ref count is increased by 1, and when a pixDestroy() call is made, the reference count of the pix is decremented. The pix is only destroyed when the reference count goes to zero. (6) The version numbers (below) are used in the serialization of these data structures. They are placed in the files, and rarely (if ever) change. (7) The serialization dependencies are as follows: pixaa : pixa : boxa boxaa : boxa So, for example, pixaa and boxaa can be changed without forcing a change in pixa or boxa. However, if pixa is changed, it forces a change in pixaa, and if boxa is changed, if forces a change in the other three. We define four version numbers: PIXAA_VERSION_NUMBER PIXA_VERSION_NUMBER BOXAA_VERSION_NUMBER BOXA_VERSION_NUMBER pre

Definition in file pix_internal.h.

Macro Definition Documentation

◆ BOXA_VERSION_NUMBER

#define BOXA_VERSION_NUMBER   2

Version for Boxa serialization

Definition at line 228 of file pix_internal.h.

◆ BOXAA_VERSION_NUMBER

#define BOXAA_VERSION_NUMBER   3

Version for Boxaa serialization

Definition at line 229 of file pix_internal.h.

◆ DPIX_VERSION_NUMBER

#define DPIX_VERSION_NUMBER   2

Version for DPix serialization

Definition at line 372 of file pix_internal.h.

◆ FPIX_VERSION_NUMBER

#define FPIX_VERSION_NUMBER   2

Version for FPix serialization

Definition at line 343 of file pix_internal.h.

◆ PIXA_VERSION_NUMBER

#define PIXA_VERSION_NUMBER   2

Version for Pixa serialization

Definition at line 227 of file pix_internal.h.

◆ PIXAA_VERSION_NUMBER

#define PIXAA_VERSION_NUMBER   2

Version for Pixaa serialization

Definition at line 226 of file pix_internal.h.

◆ PIXACOMP_VERSION_NUMBER

#define PIXACOMP_VERSION_NUMBER   2

Version for PixaComp serialization

Definition at line 414 of file pix_internal.h.

◆ PTA_VERSION_NUMBER

#define PTA_VERSION_NUMBER   1

Version for Pta serialization

Definition at line 285 of file pix_internal.h.