0
# Core Image Structures
1

2
Primary image containers supporting multiple bit depths, color models, and automatic memory management for comprehensive image processing operations.
3

4
## Capabilities
5

6
### PIX - Primary Image Structure
7

8
The main image container supporting 1, 2, 4, 8, 16, and 32 bits per pixel with automatic memory management.
9

10
```java { .api }
11
/**
12
 * Primary image structure supporting multiple bit depths and color models
13
 */
14
class PIX extends AbstractPIX {
15
    // Factory methods with automatic memory management
16
    static PIX create(int width, int height, int depth);
17
    static PIX createNoInit(int width, int height, int depth);
18
    static PIX createTemplate(PIX pixs);
19
    static PIX createTemplateNoInit(PIX pixs);
20
    static PIX createHeader(int width, int height, int depth);
21
    
22
    // Cloning with memory management
23
    PIX clone();
24
    
25
    // Image dimensions and properties
26
    int w(); // width in pixels
27
    int h(); // height in pixels  
28
    int d(); // depth in bits per pixel (1, 2, 4, 8, 16, 32)
29
    int spp(); // samples per pixel
30
    int wpl(); // 32-bit words per line
31
    int refcount(); // reference count
32
    
33
    // Resolution information
34
    int xres(); // horizontal resolution in pixels per inch
35
    int yres(); // vertical resolution in pixels per inch
36
    
37
    // Format and metadata
38
    int informat(); // input file format (IFF_* constants)
39
    int special(); // special processing instructions
40
    BytePointer text(); // associated text string
41
    
42
    // Image data access
43
    IntPointer data(); // raw image data
44
    PIXCMAP colormap(); // color palette (may be null)
45
    
46
    // Java integration methods
47
    ByteBuffer createBuffer(); // ByteBuffer view of image data
48
    UByteIndexer createIndexer(); // Indexer for pixel access
49
    void destroy(); // manual cleanup
50
}
51
```
52

53
**Usage Examples:**
54

55
```java
56
import org.bytedeco.leptonica.*;
57
import static org.bytedeco.leptonica.global.leptonica.*;
58

59
// Create a new 8-bit grayscale image
60
PIX pix = PIX.create(640, 480, 8);
61

62
// Create from template (copies dimensions)
63
PIX template = PIX.createTemplate(sourcePix);
64

65
// Access image properties
66
int width = pix.w();
67
int height = pix.h();
68
int depth = pix.d();
69
System.out.println("Image: " + width + "x" + height + "x" + depth + " bpp");
70

71
// Get raw data access for custom processing
72
IntPointer data = pix.data();
73
ByteBuffer buffer = pix.createBuffer();
74

75
// Memory is automatically managed - no manual cleanup needed
76
```
77

78
### AbstractPIX - Memory Management Base
79

80
Abstract base class providing automatic memory management and Java integration for PIX objects.
81

82
```java { .api }
83
/**
84
 * Abstract base providing automatic memory management for PIX objects
85
 */
86
abstract class AbstractPIX extends Pointer implements Indexable {
87
    // Factory methods register automatic cleanup
88
    static PIX create(int width, int height, int depth);
89
    static PIX createNoInit(int width, int height, int depth);
90
    static PIX createTemplate(PIX pixs);
91
    static PIX createTemplateNoInit(PIX pixs);
92
    static PIX createHeader(int width, int height, int depth);
93
    static PIX create(int width, int height, int depth, Pointer data);
94
    
95
    // Clone with automatic memory management
96
    PIX clone();
97
    
98
    // Java integration
99
    ByteBuffer createBuffer();
100
    ByteBuffer createBuffer(int index);
101
    UByteIndexer createIndexer();
102
    UByteIndexer createIndexer(boolean direct);
103
    
104
    // Manual cleanup (optional)
105
    void destroy();
106
}
107
```
108

109
### FPIX - Float Pixel Image
110

111
32-bit floating point image container for high-precision processing operations.
112

113
```java { .api }
114
/**
115
 * 32-bit floating point image container
116
 */
117
class FPIX extends AbstractFPIX {
118
    // Similar structure to PIX but for float data
119
    int w(); // width in pixels
120
    int h(); // height in pixels
121
    int wpl(); // words per line
122
    int refcount(); // reference count
123
    
124
    int xres(); // horizontal resolution  
125
    int yres(); // vertical resolution
126
    
127
    FloatPointer data(); // float image data
128
}
129

130
/**
131
 * Abstract base for FPIX with automatic memory management
132
 */
133
abstract class AbstractFPIX extends Pointer {
134
    // Factory methods with cleanup registration
135
    static FPIX create(int width, int height);
136
    static FPIX createTemplate(FPIX fpixs);
137
    
138
    FPIX clone();
139
    void destroy();
140
}
141
```
142

143
**Usage Examples:**
144

145
```java
146
// Create float image for high-precision processing
147
FPIX fpix = AbstractFPIX.create(640, 480);
148

149
// Convert from PIX to FPIX for floating point operations
150
FPIX floatImage = pixConvertToFPix(sourcePix, 1);
151

152
// Access float data
153
FloatPointer floatData = fpix.data();
154
```
155

156
### DPIX - Double Pixel Image
157

158
64-bit double precision image container for maximum precision in mathematical operations.
159

160
```java { .api }
161
/**
162
 * 64-bit double precision image container
163
 */
164
class DPIX extends AbstractDPIX {
165
    int w(); // width in pixels
166
    int h(); // height in pixels  
167
    int wpl(); // words per line
168
    int refcount(); // reference count
169
    
170
    int xres(); // horizontal resolution
171
    int yres(); // vertical resolution
172
    
173
    DoublePointer data(); // double image data
174
}
175

176
/**
177
 * Abstract base for DPIX with automatic memory management  
178
 */
179
abstract class AbstractDPIX extends Pointer {
180
    static DPIX create(int width, int height);
181
    static DPIX createTemplate(DPIX dpixs);
182
    
183
    DPIX clone();
184
    void destroy();
185
}
186
```
187

188
### Global Image Functions
189

190
Core functions for creating, manipulating, and analyzing images across all types.
191

192
```java { .api }
193
// PIX creation and destruction (use Abstract factory methods instead)
194
PIX pixCreate(int width, int height, int depth);
195
PIX pixCreateNoInit(int width, int height, int depth);
196
PIX pixCreateTemplate(PIX pixs);
197
void pixDestroy(PIX pix);
198

199
// Property access
200
int pixGetWidth(PIX pix);
201
int pixGetHeight(PIX pix);
202
int pixGetDepth(PIX pix);
203
int pixGetSpp(PIX pix);
204
int pixGetWpl(PIX pix);
205
int pixGetRefcount(PIX pix);
206
int pixGetXRes(PIX pix);
207
int pixGetYRes(PIX pix);
208
IntPointer pixGetData(PIX pix);
209
PIXCMAP pixGetColormap(PIX pix);
210
BytePointer pixGetText(PIX pix);
211

212
// Property modification
213
int pixSetSpp(PIX pix, int spp);
214
int pixSetText(PIX pix, String textstring);
215
int pixSetResolution(PIX pix, int xres, int yres);
216
int pixSetColormap(PIX pix, PIXCMAP colormap);
217

218
// Image copying and cloning
219
PIX pixCopy(PIX pixd, PIX pixs);
220
PIX pixClone(PIX pixs);
221
PIX pixClipRectangle(PIX pixs, BOX box, IntPointer pboxc);
222

223
// FPIX functions
224
FPIX fpixCreate(int width, int height);
225
void fpixDestroy(FPIX fpix);
226
int fpixGetWidth(FPIX fpix);
227
int fpixGetHeight(FPIX fpix);
228
FloatPointer fpixGetData(FPIX fpix);
229

230
// DPIX functions  
231
DPIX dpixCreate(int width, int height);
232
void dpixDestroy(DPIX dpix);
233
DoublePointer dpixGetData(DPIX dpix);
234

235
// Type conversions
236
FPIX pixConvertToFPix(PIX pixs, int ncomps);
237
DPIX pixConvertToDPix(PIX pixs, int ncomps);
238
PIX fpixConvertToPix(FPIX fpix, int outdepth, int negvals, int errorflag);
239
PIX dpixConvertToPix(DPIX dpix, int outdepth, int negvals, int errorflag);
240
```
241

242
**Usage Examples:**
243

244
```java
245
// Get image dimensions using global functions
246
int width = pixGetWidth(pix);
247
int height = pixGetHeight(pix);
248
int depth = pixGetDepth(pix);
249

250
// Access raw data
251
IntPointer data = pixGetData(pix);
252

253
// Set image text metadata
254
pixSetText(pix, "Processed image");
255

256
// Set resolution
257
pixSetResolution(pix, 300, 300); // 300 DPI
258

259
// Clone image (increases reference count)
260
PIX cloned = pixClone(pix);
261

262
// Extract rectangular region
263
BOX region = boxCreate(100, 100, 200, 150);
264
PIX clipped = pixClipRectangle(pix, region, null);
265
```
266

267
## Memory Management Details
268

269
The JavaCPP binding provides sophisticated memory management:
270

271
1. **Automatic Cleanup**: Abstract factory methods register deallocators automatically
272
2. **Reference Counting**: Native reference counting prevents premature deallocation  
273
3. **Manual Control**: `destroy()` methods available for explicit cleanup
274
4. **Java Integration**: ByteBuffer and Indexer provide safe data access
275

276
```java
277
// Recommended: Use Abstract factory methods
278
PIX pix = PIX.create(640, 480, 8); // Automatic cleanup registered
279

280
// Access data safely through Java interfaces
281
ByteBuffer buffer = pix.createBuffer();
282
UByteIndexer indexer = pix.createIndexer();
283

284
// Memory automatically freed when Java object is garbage collected
285
// Manual cleanup optional: pix.destroy();
286
```
287

288
## Supported Image Types
289

290
- **1 bpp**: Binary images, with and without colormap
291
- **2 bpp**: 4-color images, with and without colormap  
292
- **4 bpp**: 16-color images, with and without colormap
293
- **8 bpp**: 256-color or grayscale images, with and without colormap
294
- **16 bpp**: High-depth grayscale images (1 sample per pixel)
295
- **32 bpp RGB**: Color images (3 samples per pixel)
296
- **32 bpp RGBA**: Color images with alpha channel (4 samples per pixel)
297
- **32-bit float**: High-precision grayscale (FPIX)
298
- **64-bit double**: Maximum precision grayscale (DPIX)