0
# Image Processing
1

2
Comprehensive image processing capabilities including thumbnails, advanced transformations, watermarks, and metadata extraction using Qiniu's cloud-based image processing services.
3

4
## Capabilities
5

6
### Advanced Image Processing (imageMogr2)
7

8
High-level image processing operations including resizing, cropping, rotation, and format conversion.
9

10
```typescript { .api }
11
/**
12
 * Generate advanced image processing URL
13
 * @param op - Image processing operations
14
 * @param key - Image key in storage (optional)
15
 * @param domain - Domain for direct URL generation (optional)
16
 * @returns Processing URL or URL parameter string
17
 */
18
function imageMogr2(op: ImageMogr2, key?: string, domain?: string): string;
19

20
interface ImageMogr2 {
21
  /** Auto-orient based on EXIF */
22
  'auto-orient'?: boolean;
23
  /** Remove EXIF data */
24
  strip?: boolean;
25
  /** Thumbnail size specification */
26
  thumbnail?: number;
27
  /** Crop specification */
28
  crop?: number;
29
  /** Gravity for positioning */
30
  gravity?: number;
31
  /** Output format */
32
  format?: number;
33
  /** Blur radius */
34
  blur?: number;
35
  /** Quality (1-100) */
36
  quality?: number;
37
  /** Rotation angle */
38
  rotate?: number;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { imageMogr2 } from "qiniu-js";
46

47
// Generate processing parameters only
48
const resizeParams = imageMogr2({
49
  thumbnail: 300,
50
  quality: 80,
51
  format: 1, // JPEG
52
  'auto-orient': true
53
});
54
// Returns: "imageMogr2/auto-orient/thumbnail/300/quality/80/format/1"
55

56
// Generate complete URL for immediate use
57
const processedImageUrl = imageMogr2({
58
  thumbnail: 200,
59
  crop: 200,
60
  gravity: 1, // Center
61
  strip: true
62
}, 'photos/original.jpg', 'https://cdn.example.com');
63
// Returns complete URL for processed image
64

65
// Complex processing pipeline
66
const advancedProcessing = imageMogr2({
67
  'auto-orient': true,
68
  thumbnail: 800,
69
  quality: 90,
70
  rotate: 90,
71
  blur: 3
72
});
73
```
74

75
### Image Watermarking
76

77
Add text or image watermarks to images with positioning and style control.
78

79
```typescript { .api }
80
/**
81
 * Generate watermark processing URL
82
 * @param op - Watermark configuration
83
 * @param key - Image key in storage (optional)
84
 * @param domain - Domain for direct URL generation (optional)
85
 * @returns Watermark URL or URL parameter string
86
 */
87
function watermark(op: ImageWatermark, key?: string, domain?: string): string;
88

89
interface ImageWatermark {
90
  /** Watermark mode: 1=image, 2=text */
91
  mode: number;
92
  /** Image URL for image watermarks (mode 1) */
93
  image?: string;
94
  /** Text content for text watermarks (mode 2) */
95
  text?: string;
96
  /** Font for text watermarks */
97
  font?: string;
98
  /** Font size for text watermarks */
99
  fontsize?: number;
100
  /** Text color for text watermarks */
101
  fill?: string;
102
  /** Transparency (0-100) */
103
  dissolve?: number;
104
  /** Horizontal offset */
105
  dx?: number;
106
  /** Vertical offset */
107
  dy?: number;
108
  /** Gravity for positioning */
109
  gravity?: string;
110
}
111
```
112

113
**Usage Examples:**
114

115
```typescript
116
import { watermark } from "qiniu-js";
117

118
// Text watermark
119
const textWatermark = watermark({
120
  mode: 2,
121
  text: 'Copyright 2024',
122
  font: 'SimSun',
123
  fontsize: 24,
124
  fill: '#FFFFFF',
125
  dissolve: 80,
126
  gravity: 'SouthEast',
127
  dx: 10,
128
  dy: 10
129
}, 'photos/image.jpg', 'https://cdn.example.com');
130

131
// Image watermark
132
const logoWatermark = watermark({
133
  mode: 1,
134
  image: 'https://example.com/logo.png',
135
  dissolve: 70,
136
  gravity: 'NorthWest',
137
  dx: 20,
138
  dy: 20
139
});
140

141
// Multiple positioning example
142
const centeredWatermark = watermark({
143
  mode: 2,
144
  text: 'CONFIDENTIAL',
145
  fontsize: 48,
146
  fill: '#FF0000',
147
  dissolve: 50,
148
  gravity: 'Center'
149
});
150
```
151

152
### Image Information Extraction
153

154
Retrieve basic image metadata and EXIF information.
155

156
```typescript { .api }
157
/**
158
 * Get basic image information
159
 * @param key - Image key in storage
160
 * @param domain - Storage domain
161
 * @returns Promise with image metadata
162
 */
163
function imageInfo(key: string, domain: string): Promise<ResponseSuccess<ImageInfoData>>;
164

165
/**
166
 * Get EXIF data from image
167
 * @param key - Image key in storage  
168
 * @param domain - Storage domain
169
 * @returns Promise with EXIF data
170
 */
171
function exif(key: string, domain: string): Promise<ResponseSuccess<ExifData>>;
172

173
interface ResponseSuccess<T> {
174
  data: T;
175
  reqId: string;
176
}
177
```
178

179
**Usage Examples:**
180

181
```typescript
182
import { imageInfo, exif } from "qiniu-js";
183

184
// Get basic image information
185
try {
186
  const info = await imageInfo('photos/image.jpg', 'https://cdn.example.com');
187
  console.log('Image info:', info.data);
188
  // Contains: width, height, format, size, colorModel, etc.
189
} catch (error) {
190
  console.error('Failed to get image info:', error);
191
}
192

193
// Get EXIF data
194
try {
195
  const exifData = await exif('photos/camera-shot.jpg', 'https://cdn.example.com');
196
  console.log('EXIF data:', exifData.data);
197
  // Contains: camera info, GPS data, shooting parameters, etc.
198
} catch (error) {
199
  console.error('Failed to get EXIF data:', error);
200
}
201
```
202

203
### Processing Pipeline
204

205
Chain multiple image processing operations together for complex transformations.
206

207
```typescript { .api }
208
/**
209
 * Chain multiple image processing operations
210
 * @param arr - Array of processing operations
211
 * @param key - Image key in storage (optional)
212
 * @param domain - Domain for direct URL generation (optional)
213
 * @returns Pipeline URL or URL parameter string
214
 */
215
function pipeline(arr: Pipeline[], key?: string, domain?: string): string;
216

217
type Pipeline = 
218
  | (ImageWatermark & { fop: 'watermark' })
219
  | (ImageViewOptions & { fop: 'imageView2' })
220
  | (ImageMogr2 & { fop: 'imageMogr2' });
221

222
interface ImageViewOptions {
223
  mode: number;
224
  format?: string;
225
  w?: number;
226
  h?: number;
227
  q?: number;
228
}
229
```
230

231
**Usage Examples:**
232

233
```typescript
234
import { pipeline } from "qiniu-js";
235

236
// Complex processing pipeline
237
const complexProcessing = pipeline([
238
  {
239
    fop: 'imageMogr2',
240
    'auto-orient': true,
241
    thumbnail: 800,
242
    quality: 90
243
  },
244
  {
245
    fop: 'watermark',
246
    mode: 2,
247
    text: '© 2024',
248
    fontsize: 20,
249
    fill: '#FFFFFF',
250
    gravity: 'SouthEast',
251
    dx: 10,
252
    dy: 10
253
  },
254
  {
255
    fop: 'imageView2',
256
    mode: 1,
257
    w: 600,
258
    h: 400,
259
    q: 85
260
  }
261
], 'photos/original.jpg', 'https://cdn.example.com');
262

263
// Thumbnail with watermark pipeline
264
const thumbnailPipeline = pipeline([
265
  {
266
    fop: 'imageMogr2',
267
    thumbnail: 300,
268
    crop: 300,
269
    gravity: 1
270
  },
271
  {
272
    fop: 'watermark',
273
    mode: 1,
274
    image: 'https://example.com/small-logo.png',
275
    dissolve: 60,
276
    gravity: 'NorthEast'
277
  }
278
]);
279
```
280

281
## Processing Specifications
282

283
### Thumbnail Modes
284

285
For `thumbnail` parameter in imageMogr2:
286
- Numbers represent pixel dimensions
287
- Can specify width and height constraints
288
- Maintains aspect ratio by default
289

290
### Gravity Values
291

292
Positioning reference points:
293
- `1` or `'Center'` - Center position
294
- `'NorthWest'` - Top-left corner
295
- `'North'` - Top-center
296
- `'NorthEast'` - Top-right corner
297
- `'West'` - Middle-left
298
- `'East'` - Middle-right
299
- `'SouthWest'` - Bottom-left corner
300
- `'South'` - Bottom-center
301
- `'SouthEast'` - Bottom-right corner
302

303
### Format Values
304

305
For `format` parameter:
306
- `0` - Original format
307
- `1` - JPEG
308
- `2` - GIF
309
- `3` - PNG
310
- `4` - WebP
311

312
### Quality Settings
313

314
For `quality` parameter:
315
- Range: 1-100
316
- Higher values = better quality, larger file size
317
- Recommended: 75-90 for most use cases
318

319
**Complete Example:**
320

321
```typescript
322
import { imageMogr2, watermark, pipeline, imageInfo } from "qiniu-js";
323

324
async function processUserAvatar(imageKey: string, domain: string) {
325
  try {
326
    // First get image info to check dimensions
327
    const info = await imageInfo(imageKey, domain);
328
    console.log(`Original image: ${info.data.width}x${info.data.height}`);
329
    
330
    // Create optimized avatar with watermark
331
    const avatarUrl = pipeline([
332
      {
333
        fop: 'imageMogr2',
334
        'auto-orient': true,
335
        thumbnail: 200,
336
        crop: 200,
337
        gravity: 1,
338
        quality: 90,
339
        format: 1
340
      },
341
      {
342
        fop: 'watermark',
343
        mode: 2,
344
        text: 'Profile',
345
        fontsize: 12,
346
        fill: '#FFFFFF',
347
        dissolve: 70,
348
        gravity: 'SouthEast',
349
        dx: 5,
350
        dy: 5
351
      }
352
    ], imageKey, domain);
353
    
354
    return avatarUrl;
355
  } catch (error) {
356
    console.error('Image processing failed:', error);
357
    throw error;
358
  }
359
}
360
```