0
# Image I/O Operations
1

2
Comprehensive image reading, writing, and format conversion capabilities supporting all major image formats with automatic format detection and cross-platform compatibility.
3

4
## Capabilities
5

6
### Image Reading
7

8
Read images from files, streams, or memory with automatic format detection and comprehensive format support.
9

10
```java { .api }
11
/**
12
 * Read image from file with automatic format detection
13
 * @param filename - Path to image file
14
 * @return PIX image or null on failure
15
 */
16
PIX pixRead(String filename);
17
PIX pixRead(BytePointer filename);
18

19
/**
20
 * Read image from stream with format hint
21
 * @param fp - Input stream
22
 * @param hint - Format hint (IFF_* constant or 0 for auto-detect)
23
 * @return PIX image or null on failure
24
 */
25
PIX pixReadStream(InputStream fp, int hint);
26

27
/**
28
 * Read image from memory buffer
29
 * @param data - Image data buffer
30
 * @param size - Size of data buffer in bytes
31
 * @return PIX image or null on failure
32
 */
33
PIX pixReadMem(BytePointer data, long size);
34

35
/**
36
 * Read image with color palette preserved
37
 * @param filename - Path to image file
38
 * @return PIX image with original colormap or null on failure
39
 */
40
PIX pixReadWithHint(String filename, int hint);
41

42
/**
43
 * Read image header information only (no pixel data)
44
 * @param filename - Path to image file
45
 * @param pformat - Returns detected format
46
 * @param pw - Returns image width
47
 * @param ph - Returns image height
48
 * @param pbps - Returns bits per sample
49
 * @param pspp - Returns samples per pixel  
50
 * @param piscmap - Returns 1 if colormap present
51
 * @return 0 on success, 1 on failure
52
 */
53
int pixReadHeader(String filename, IntPointer pformat, IntPointer pw, IntPointer ph, 
54
                  IntPointer pbps, IntPointer pspp, IntPointer piscmap);
55
```
56

57
**Usage Examples:**
58

59
```java
60
import org.bytedeco.leptonica.*;
61
import static org.bytedeco.leptonica.global.leptonica.*;
62

63
// Read image with automatic format detection
64
PIX pix = pixRead("image.jpg");
65
if (pix == null) {
66
    System.err.println("Failed to read image");
67
    return;
68
}
69

70
// Read from memory buffer
71
byte[] imageData = Files.readAllBytes(Paths.get("image.png"));
72
BytePointer buffer = new BytePointer(imageData);
73
PIX pixFromMem = pixReadMem(buffer, imageData.length);
74

75
// Get image info without loading pixel data
76
IntPointer format = new IntPointer(1);
77
IntPointer width = new IntPointer(1);  
78
IntPointer height = new IntPointer(1);
79
IntPointer bps = new IntPointer(1);
80
IntPointer spp = new IntPointer(1);
81
IntPointer iscmap = new IntPointer(1);
82

83
int result = pixReadHeader("image.tiff", format, width, height, bps, spp, iscmap);
84
if (result == 0) {
85
    System.out.println("Image: " + width.get() + "x" + height.get() + 
86
                      ", " + bps.get() + " bps, " + spp.get() + " spp");
87
}
88
```
89

90
### Image Writing
91

92
Write images to files, streams, or memory with format-specific options and quality settings.
93

94
```java { .api }
95
/**
96
 * Write image to file with specified format
97
 * @param filename - Output file path
98
 * @param pix - Image to write
99
 * @param format - Output format (IFF_* constant)
100
 * @return 0 on success, 1 on failure
101
 */
102
int pixWrite(String filename, PIX pix, int format);
103
int pixWrite(BytePointer filename, PIX pix, int format);
104

105
/**
106
 * Write image to stream
107
 * @param fp - Output stream
108
 * @param pix - Image to write
109
 * @param format - Output format (IFF_* constant)
110
 * @return 0 on success, 1 on failure
111
 */
112
int pixWriteStream(OutputStream fp, PIX pix, int format);
113

114
/**
115
 * Write image to memory buffer
116
 * @param pix - Image to write
117
 * @param psize - Returns size of generated data
118
 * @param format - Output format (IFF_* constant)
119
 * @return BytePointer to image data or null on failure
120
 */
121
BytePointer pixWriteMem(PIX pix, long[] psize, int format);
122

123
/**
124
 * Write image with format-specific parameters
125
 * @param filename - Output file path
126
 * @param pix - Image to write  
127
 * @param format - Output format
128
 * @param quality - JPEG quality (1-100) or PNG compression (0-9)
129
 * @return 0 on success, 1 on failure
130
 */
131
int pixWriteImpliedFormat(String filename, PIX pix, int quality, int progressive);
132
```
133

134
**Usage Examples:**
135

136
```java
137
// Write image in PNG format
138
int result = pixWrite("output.png", pix, IFF_PNG);
139
if (result != 0) {
140
    System.err.println("Failed to write PNG");
141
}
142

143
// Write JPEG with quality setting
144
result = pixWriteImpliedFormat("output.jpg", pix, 85, 0);
145

146
// Write to memory buffer
147
long[] size = new long[1];
148
BytePointer buffer = pixWriteMem(pix, size, IFF_PNG);
149
if (buffer != null) {
150
    System.out.println("Generated " + size[0] + " bytes of PNG data");
151
    
152
    // Save buffer to file or process further
153
    byte[] imageBytes = new byte[(int)size[0]];
154
    buffer.get(imageBytes);
155
    Files.write(Paths.get("output.png"), imageBytes);
156
}
157
```
158

159
### Format Constants
160

161
Supported image format identifiers for reading and writing operations.
162

163
```java { .api }
164
// Primary image formats
165
static final int IFF_UNKNOWN = 0;
166
static final int IFF_BMP = 1;
167
static final int IFF_JFIF_JPEG = 2;
168
static final int IFF_PNG = 3;
169
static final int IFF_TIFF = 4;
170
static final int IFF_TIFF_PACKBITS = 5;
171
static final int IFF_TIFF_RLE = 6;
172
static final int IFF_TIFF_G3 = 7;
173
static final int IFF_TIFF_G4 = 8;
174
static final int IFF_TIFF_LZW = 9;
175
static final int IFF_TIFF_ZIP = 10;
176
static final int IFF_PNM = 11;
177
static final int IFF_PS = 12; 
178
static final int IFF_GIF = 13;
179
static final int IFF_JP2 = 14;
180
static final int IFF_WEBP = 15;
181
static final int IFF_LPDF = 16;
182
static final int IFF_DEFAULT = 17;
183

184
// TIFF compression formats
185
static final int IFF_TIFF_JPEG = 18;
186

187
// Legacy aliases
188
static final int IFF_JPEG = IFF_JFIF_JPEG;
189
```
190

191
### Format-Specific Functions
192

193
Specialized functions for format-specific operations and advanced I/O control.
194

195
```java { .api }
196
// JPEG operations
197
PIX pixReadJpeg(String filename, int cmflag, int reduction, IntPointer pnwarn, int hint);
198
int pixWriteJpeg(String filename, PIX pix, int quality, int progressive);
199

200
// PNG operations  
201
PIX pixReadPng(String filename, int hint);
202
int pixWritePng(String filename, PIX pix, float gamma);
203

204
// TIFF operations
205
PIX pixReadTiff(String filename, int n);
206
int pixWriteTiff(String filename, PIX pix, int comptype, String modestring);
207
PIXA pixaReadMultipageTiff(String filename);
208
int pixaWriteMultipageTiff(String filename, PIXA pixa);
209

210
// GIF operations
211
PIX pixReadGif(String filename);
212
int pixWriteGif(String filename, PIX pix);
213

214
// WebP operations  
215
PIX pixReadWebP(String filename);
216
int pixWriteWebP(String filename, PIX pix, int quality, int lossless);
217

218
// PNM (PPM/PGM/PBM) operations
219
PIX pixReadPnm(String filename);
220
int pixWritePnm(String filename, PIX pix);
221

222
// PostScript operations
223
int pixWritePS(String filename, PIX pix, BOX box, int res, int scale);
224
int pixWritePSEmbed(String filename, PIX pix, BOX box);
225

226
// PDF operations
227
int pixWritePdf(String filename, PIX pix, int res, String title, IntPointer plpd);
228
```
229

230
**Usage Examples:**
231

232
```java
233
// Read JPEG with specific options
234
IntPointer warnings = new IntPointer(1);
235
PIX jpegPix = pixReadJpeg("photo.jpg", 0, 2, warnings, 0); // 1/4 size reduction
236
if (warnings.get() > 0) {
237
    System.out.println("JPEG read with " + warnings.get() + " warnings");
238
}
239

240
// Write high-quality JPEG
241
pixWriteJpeg("output.jpg", pix, 95, 1); // 95% quality, progressive
242

243
// Read multi-page TIFF
244
PIXA pages = pixaReadMultipageTiff("document.tiff");
245
int pageCount = pixaGetCount(pages);
246
System.out.println("Document has " + pageCount + " pages");
247

248
// Write WebP with lossless compression
249
pixWriteWebP("output.webp", pix, 100, 1); // lossless
250

251
// Write PostScript with specific resolution
252
BOX fullPage = boxCreate(0, 0, pixGetWidth(pix), pixGetHeight(pix));
253
pixWritePS("output.ps", pix, fullPage, 300, 1);
254
```
255

256
### Image Information and Validation
257

258
Functions for querying image properties and validating image data.
259

260
```java { .api }
261
/**
262
 * Get image format from file
263
 * @param filename - Path to image file
264
 * @return Format constant (IFF_*) or IFF_UNKNOWN
265
 */
266
int pixGetInputFormat(PIX pix);
267
String getImagelibVersions();
268

269
/**
270
 * Determine if file contains valid image data
271
 * @param filename - Path to file
272
 * @return 1 if valid image, 0 otherwise
273
 */
274
int pixGetImageIOVersion();
275

276
/**
277
 * Check if specific format is supported
278
 * @param format - Format to check (IFF_* constant)
279
 * @return 1 if supported, 0 otherwise  
280
 */
281
int formatSupported(int format);
282
```
283

284
**Usage Examples:**
285

286
```java
287
// Check image format
288
int format = pixGetInputFormat(pix);
289
switch (format) {
290
    case IFF_PNG:
291
        System.out.println("PNG image");
292
        break;
293
    case IFF_JPEG:
294
        System.out.println("JPEG image");
295
        break;
296
    case IFF_TIFF:
297
        System.out.println("TIFF image");
298
        break;
299
    default:
300
        System.out.println("Unknown or unsupported format");
301
}
302

303
// Get library version information
304
String versions = getImagelibVersions();
305
System.out.println("Image libraries: " + versions);
306

307
// Check format support
308
if (formatSupported(IFF_WEBP) == 1) {
309
    System.out.println("WebP format is supported");
310
}
311
```
312

313
## Error Handling
314

315
I/O functions follow consistent error handling patterns:
316

317
- **Return Values**: 0 indicates success, 1 indicates failure for write operations
318
- **Null Returns**: PIX reading functions return null on failure
319
- **Validation**: Always check return values and null pointers
320

321
```java
322
// Proper error handling pattern
323
PIX pix = pixRead("input.jpg");
324
if (pix == null) {
325
    System.err.println("Failed to read input.jpg");
326
    return;
327
}
328

329
int result = pixWrite("output.png", pix, IFF_PNG);
330
if (result != 0) {
331
    System.err.println("Failed to write output.png");
332
    return;
333
}
334

335
System.out.println("Image conversion successful");
336
```
337

338
## Performance Considerations
339

340
- **Format Detection**: Automatic detection adds minimal overhead
341
- **Memory Reading**: `pixReadMem()` is efficient for pre-loaded data
342
- **Streaming**: Use streams for large files or network sources
343
- **Header Reading**: `pixReadHeader()` avoids loading pixel data for metadata-only operations
344
- **Quality Settings**: Higher JPEG quality increases file size significantly
345
- **Compression**: PNG and TIFF compression trades CPU time for smaller files