Image Processing
Image processing pipeline: react-easy-crop frontend editor sends crop coordinates to the backend. bimg/libvips performs crop, resize, format conversion to WebP/AVIF, and compression 80–90%. Timeout 30s. Max 10 MB. SDK: uploadImage(), processImage().
Every module that uses kernel.files() automatically gets a full image
processing pipeline. Modules never need to implement their own resize,
crop, or format conversion — the kernel handles it transparently.
Technical Stack
| Component | Library | Role |
|---|---|---|
| Backend | bimg (libvips, Go binding) | Crop, resize, convert, compress. C library used by Netflix and AWS |
| Frontend | react-easy-crop | Interactive crop editor: grid, zoom, drag, aspect ratio lock, rotation |
| Output formats | WebP, AVIF, PNG, JPEG, SVG | Auto-selected by backend |
Upload + Processing Pipeline
When a user uploads an image through the <ImageUpload> component
or uploadImage(), the following steps execute automatically:
1. User selects file in browser
2. Frontend — react-easy-crop editor:
Grid crop overlay (Instagram-style)
Zoom: pinch gesture or slider
Drag to reposition crop area
Aspect ratio lock: 1:1, 16:9, 3:1 (configured per module)
Rotation
3. Frontend sends:
Original file + crop parameters { x, y, width, height, zoom }
4. Backend — bimg/libvips:
Crop by coordinates
Resize to target dimensions
Convert: WebP by default, PNG if transparency detected
Compress: quality 80–90% (visually lossless, size −60–80%)
Generate thumbnail presets (icon_32 + card_300 always, others on-demand)
Timeout: 30 s (FILES_IMAGE_PROCESSING_TIMEOUT_SEC)
→ on timeout: original saved, thumbnails = pending (background retry)
Limit: 10 MB max (FILES_MAX_IMAGE_SIZE_MB)
→ above limit: 413 Payload Too Large
5. Save to S3:
Original file
Processed file (cropped + resized + converted)
Auto-generated thumbnailsSDK — uploadImage()
Upload an image with crop parameters in a single call:
import { kernel } from '@platform/sdk-core';
const result = await kernel.files().uploadImage({
file: imageFile, // File | Blob | Buffer
filename: 'profile-photo.png',
bucket: 'avatars',
crop: {
x: 120,
y: 80,
width: 400,
height: 400,
zoom: 1.2,
},
outputFormat: 'webp', // 'webp' | 'avif' | 'png' | 'jpeg' — default 'webp'
quality: 85, // 1–100 — default 85
aspectRatio: '1:1',
});
// result:
// {
// fileId: '01j9paf1l000000000000000',
// originalUrl: 'https://api.septemcore.com/v1/files/01j9paf1l...',
// processedUrl: 'https://api.septemcore.com/v1/files/01j9paf1l.../processed',
// thumbnails: {
// icon_32: 'https://api.septemcore.com/v1/files/01j9paf1l.../thumbnail/icon_32',
// card_300: 'https://api.septemcore.com/v1/files/01j9paf1l.../thumbnail/card_300'
// },
// size: 84320,
// compressionRatio: '72%',
// status: 'available'
// }SDK — processImage()
Process an already-uploaded image (run or re-run bimg operations):
const result = await kernel.files().processImage({
fileId: '01j9paf1l000000000000000',
operations: {
crop: { x: 0, y: 0, width: 800, height: 600 },
resize: { width: 400, height: 300 },
format: 'avif',
quality: 80,
rotate: 90,
},
});
// result:
// {
// fileId: '01j9paf1l000000000000000',
// processedUrl: 'https://api.septemcore.com/v1/files/01j9paf1l.../processed',
// size: 61440,
// status: 'available'
// }REST — POST /files/:id/process
POST https://api.septemcore.com/v1/files/01j9paf1l000000000000000/process
Authorization: Bearer <access_token>
Content-Type: application/json
{
"operations": {
"crop": { "x": 0, "y": 0, "width": 800, "height": 600 },
"resize": { "width": 400, "height": 300 },
"format": "avif",
"quality": 80,
"rotate": 90
}
}Response 200 OK:
{
"fileId": "01j9paf1l000000000000000",
"processedUrl": "https://api.septemcore.com/v1/files/01j9paf1l.../processed",
"size": 61440,
"status": "available"
}Output Format Selection
| Format | When used | Notes |
|---|---|---|
webp | Default for all images | 30–40% smaller than JPEG at same quality |
avif | Explicit request or AVIF-capable CDN config | 50% smaller than JPEG, slower encode |
png | Transparency detected or explicitly requested | Lossless, larger file size |
jpeg | Explicit request for JPEG output | Legacy compatibility |
svg | Passthrough only — not processed by bimg | SVG is not rasterized |
Processing Limits and Timeouts
| Parameter | Value | Env variable |
|---|---|---|
| Max image size | 10 MB | FILES_MAX_IMAGE_SIZE_MB=10 |
| Processing timeout | 30 seconds | FILES_IMAGE_PROCESSING_TIMEOUT_SEC=30 |
| Timeout behaviour | Original saved; thumbnails = pending → background retry | — |
| Quality range | 1–100 (default 85) | — |
| Max output dimensions | 8 000 × 8 000 px | libvips internal limit |
Frontend — ImageUpload Component
UI Shell provides a ready-made <ImageUpload> component with the
built-in crop editor. Modules drop it in without implementing any
crop UI:
import { ImageUpload } from '@platform/ui-shell';
<ImageUpload
bucket="avatars"
aspectRatio="1:1"
maxSizeMb={10}
outputFormat="webp"
presets={['icon_32', 'avatar_64', 'card_300']}
onUploadComplete={(result) => {
// result.fileId, result.thumbnails.avatar_64, result.processedUrl
setAvatarUrl(result.thumbnails.avatar_64);
}}
/>| Prop | Description |
|---|---|
bucket | Target logical bucket (avatars, assets, documents, exports, modules) |
aspectRatio | Lock crop ratio: '1:1' for avatars, '3:1' for banners, '16:9' for covers |
maxSizeMb | Client-side size validation before upload (in addition to server 10 MB limit) |
outputFormat | Target format: 'webp' (default), 'avif', 'png', 'jpeg' |
presets | Thumbnail presets to generate. icon_32 and card_300 are always generated |
onUploadComplete | Callback receiving the full upload result |
Error Reference
| Scenario | HTTP | Code |
|---|---|---|
| File exceeds 10 MB | 413 | PAYLOAD_TOO_LARGE |
| Processing timeout (30 s) | 202 | Original saved; thumbnails retried in background |
| Invalid crop coordinates | 400 | validation-error |
| Unsupported source format | 422 | UNSUPPORTED_FORMAT |
| File not found | 404 | not-found |
Downloading Files
Two download methods: GET /files/:id streams binary directly; GET /files/:id/url returns a short-lived presigned URL for direct S3 download. Both enforce JWT tenantId check. Cross-tenant file access is structurally impossible.
Thumbnail Presets
5 thumbnail presets: icon_32 (32x32), avatar_64 (64x64), card_300 (300x200), preview_600 (600x400), full_1200 (1200xauto). icon_32 and card_300 are auto-generated on upload. Others are on-demand. GET /files/:id/thumbnail/:preset.