0
# Crop Service
1

2
The CropService handles the actual image cropping operations, performing canvas manipulations to extract the selected image portion with support for transformations and various output formats.
3

4
## Capabilities
5

6
### Crop Service Class
7

8
Injectable service for performing image cropping operations.
9

10
```typescript { .api }
11
export class CropService {
12
  /**
13
   * Crop image to blob format
14
   * @param input - Crop input parameters including image, cropper position, and options
15
   * @param output - Output type 'blob'
16
   * @returns Promise resolving to ImageCroppedEvent with blob data, or null if cropping fails
17
   */
18
  crop(input: CropInput, output: 'blob'): Promise<ImageCroppedEvent> | null;
19

20
  /**
21
   * Crop image to base64 format  
22
   * @param input - Crop input parameters including image, cropper position, and options
23
   * @param output - Output type 'base64'
24
   * @returns ImageCroppedEvent with base64 data, or null if cropping fails
25
   */
26
  crop(input: CropInput, output: 'base64'): ImageCroppedEvent | null;
27

28
  /**
29
   * Generic crop method supporting both output types
30
   * @param input - Crop input parameters
31
   * @param output - Output type ('base64' | 'blob')  
32
   * @returns Promise<ImageCroppedEvent> | ImageCroppedEvent | null depending on output type
33
   */
34
  crop(input: CropInput, output: OutputType): Promise<ImageCroppedEvent> | ImageCroppedEvent | null;
35

36
  /**
37
   * Calculate resize ratio based on target dimensions and options
38
   * @param width - Current width
39
   * @param height - Current height
40
   * @param options - Resize options including target dimensions and scale restrictions
41
   * @returns Resize ratio to apply
42
   */
43
  getResizeRatio(width: number, height: number, options?: {
44
    resizeToWidth?: number;
45
    resizeToHeight?: number;
46
    onlyScaleDown?: boolean;
47
  }): number;
48

49
  /**
50
   * Get image quality value from options
51
   * @param options - Options containing imageQuality setting
52
   * @returns Quality value between 0 and 1
53
   */
54
  getQuality(options?: { imageQuality?: number }): number;
55
}
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import { CropService } from 'ngx-image-cropper';
62

63
// Using the crop service directly
64
const cropService = new CropService();
65

66
// Crop to base64
67
const cropInput: CropInput = {
68
  loadedImage: loadedImage,
69
  cropper: { x1: 10, y1: 10, x2: 200, y2: 150 },
70
  maxSize: { width: 400, height: 300 },
71
  transform: { scale: 1, rotate: 0 },
72
  options: {
73
    format: 'png',
74
    imageQuality: 90,
75
    backgroundColor: '#ffffff'
76
  }
77
};
78

79
const base64Result = cropService.crop(cropInput, 'base64');
80
if (base64Result) {
81
  console.log('Base64 result:', base64Result.base64);
82
}
83

84
// Crop to blob
85
const blobResult = await cropService.crop(cropInput, 'blob');
86
if (blobResult && blobResult.blob) {
87
  // Upload or process the blob
88
  const formData = new FormData();
89
  formData.append('image', blobResult.blob, 'cropped.png');
90
}
91

92
// Calculate resize ratio
93
const resizeRatio = cropService.getResizeRatio(800, 600, {
94
  resizeToWidth: 400,
95
  resizeToHeight: 300,
96
  onlyScaleDown: true
97
});
98
console.log('Resize ratio:', resizeRatio);
99

100
// Get quality value
101
const quality = cropService.getQuality({ imageQuality: 85 });
102
console.log('Quality:', quality); // 0.85
103
```
104

105
### Crop Input Interface
106

107
Input parameters required for cropping operations.
108

109
```typescript { .api }
110
interface CropInput {
111
  /** Loaded image data with original and transformed versions */
112
  loadedImage: LoadedImage;
113
  /** Cropper position coordinates */
114
  cropper: CropperPosition;
115
  /** Maximum size constraints */
116
  maxSize: Dimensions;
117
  /** Image transformation settings */
118
  transform?: ImageTransform;
119
  /** Cropping options */
120
  options?: {
121
    backgroundColor?: string;
122
    containWithinAspectRatio?: boolean;
123
    maintainAspectRatio?: boolean;
124
    aspectRatio?: number;
125
    format?: OutputFormat;
126
    canvasRotation?: number;
127
    imageQuality?: number;
128
    resizeToWidth?: number;
129
    resizeToHeight?: number;
130
    onlyScaleDown?: boolean;
131
  };
132
}
133
```
134

135
### Resize Options
136

137
Options for controlling image resizing behavior.
138

139
```typescript { .api }
140
interface ResizeOptions {
141
  /** Target width for resizing */
142
  resizeToWidth?: number;
143
  /** Target height for resizing */
144
  resizeToHeight?: number;
145
  /** Only scale down, never scale up */
146
  onlyScaleDown?: boolean;
147
}
148
```
149

150
### Output Types
151

152
Type definitions for crop service outputs.
153

154
```typescript { .api }
155
type OutputType = 'base64' | 'blob';
156

157
interface ImageCroppedEvent {
158
  /** Base64 encoded image data (when output type is 'base64') */
159
  base64?: string | null;
160
  /** Blob containing image data (when output type is 'blob') */
161
  blob?: Blob | null;
162
  /** Object URL for the blob (when output type is 'blob') */
163
  objectUrl?: string | null;
164
  /** Width of the cropped image */
165
  width: number;
166
  /** Height of the cropped image */
167
  height: number;
168
  /** Position of the cropper within the display */
169
  cropperPosition: CropperPosition;
170
  /** Position of the crop within the actual image */
171
  imagePosition: CropperPosition;
172
  /** Offset image position (when containWithinAspectRatio is enabled) */
173
  offsetImagePosition?: CropperPosition;
174
}
175
```
176

177
### Advanced Usage
178

179
```typescript
180
// Custom cropping with specific transformations
181
const advancedCropInput: CropInput = {
182
  loadedImage: myLoadedImage,
183
  cropper: { x1: 50, y1: 50, x2: 300, y2: 200 },
184
  maxSize: { width: 800, height: 600 },
185
  transform: {
186
    scale: 1.2,
187
    rotate: 15,
188
    flipH: false,
189
    flipV: true,
190
    translateH: 10,
191
    translateV: -5,
192
    translateUnit: 'px'
193
  },
194
  options: {
195
    format: 'jpeg',
196
    imageQuality: 95,
197
    backgroundColor: '#f0f0f0',
198
    resizeToWidth: 512,
199
    resizeToHeight: 384,
200
    onlyScaleDown: false,
201
    maintainAspectRatio: true,
202
    containWithinAspectRatio: true
203
  }
204
};
205

206
// Perform cropping with transformations
207
const croppedResult = await cropService.crop(advancedCropInput, 'blob');
208
if (croppedResult) {
209
  console.log(`Cropped to ${croppedResult.width}x${croppedResult.height}`);
210
  console.log('Cropper position:', croppedResult.cropperPosition);
211
  console.log('Image position:', croppedResult.imagePosition);
212
  
213
  if (croppedResult.offsetImagePosition) {
214
    console.log('Offset position:', croppedResult.offsetImagePosition);
215
  }
216
}
217

218
// Utility methods
219
const resizeRatio = cropService.getResizeRatio(1920, 1080, {
220
  resizeToWidth: 800,
221
  onlyScaleDown: true
222
});
223

224
const qualityValue = cropService.getQuality({ imageQuality: 80 });
225
```