Aller au contenu
Tous les travaux

Open sourceEn ligne

imgkit

Traitement d'image rapide pour Bun et Node.js, avec un cœur en Rust et une API typée.

Statut
En ligne
Année
2025
Rôle
Auteur

Redimensionner, recadrer, convertir, filigraner et analyser des images depuis JavaScript, le travail étant fait en Rust natif. Des binaires précompilés pour sept plateformes, un repli WebAssembly pour les autres, le HEIC des iPhone sur macOS ARM64, et plus rapide que sharp dans les benchmarks du projet.

Ce que c'est

  • Rust natif via napi-rs : JPEG en SIMD avec libjpeg-turbo, décodage à 1/2, 1/4 ou 1/8 de la taille quand la cible est petite, et des Buffers qui passent dans Rust sans copie
  • Bien plus que le redimensionnement : recadrage intelligent, filigranes avec modes de fusion, couleurs dominantes, hachages perceptuels, placeholders ThumbHash et BlurHash, EXIF et tenseurs prêts pour le ML
  • Chaque appel asynchrone tourne hors de la boucle d'événements et accepte un délai maximal et un AbortSignal ; chaque fonction de traitement a sa jumelle synchrone
  • Précompilé pour macOS, Linux et Windows en x64 et ARM64 ; sur toute autre plateforme, Node se replie sur une build WebAssembly du même code Rust

Comment ça marche

Ce qu'il fait, le trajet d'un appel de JavaScript à Rust et retour, d'où vient la vitesse, le repli WebAssembly, et ce qui n'est pas terminé.

#Ce qu'il fait

imgkit est une bibliothèque d'image pour Bun et Node.js. Le travail se fait en Rust, compilé en module natif avec napi-rs, et JavaScript dispose d'une API typée par-dessus. Il est né sous le nom bun-image-turbo et est devenu imgkit en 2.0.0, avec la même API sous un nouveau chemin d'import.

Tout ce qui suit est livré dans la 2.4.0.

  • Lire et convertir. JPEG, PNG, WebP, GIF et BMP en entrée comme en sortie, TIFF en entrée. HEIC/HEIF et AVIF sont décodés dans la build macOS ARM64.
  • Redimensionner, recadrer, vignettes. Redimensionnement avec filtres adaptatifs, recadrage par coordonnées, ratio ou gravité, recadrage intelligent selon le contenu, et une voie dédiée aux vignettes qui décode à taille réduite.
  • Composer. Superpositions et filigranes avec sept modes de fusion, opacité, redimensionnement et répétition par calque.
  • Décrire une image. Métadonnées lues dans l'en-tête seul, couleurs dominantes, hachages perceptuels (pHash, dHash, aHash, BlockHash) pour détecter les doublons, et placeholders ThumbHash ou BlurHash.
  • Nourrir un modèle. toTensor() transforme une image en tenseur Float32 ou Uint8 avec normalisation ImageNet ou CLIP, en disposition CHW ou HWC, prêt pour ONNX Runtime, PyTorch ou TensorFlow.js.
  • EXIF. Écrire et supprimer les métadonnées EXIF sur JPEG et WebP.
  • Contrôle. Chaque fonction de traitement existe en version asynchrone et synchrone. Chaque appel asynchrone accepte timeoutMs et un AbortSignal.

#En pratique

ts
import { metadata, transform, thumbhash } from 'imgkit';

const buf = Buffer.from(await Bun.file('photo.jpg').arrayBuffer());

const info = await metadata(buf);           // lit uniquement l'en-tête

const webp = await transform(buf, {         // un décodage, un encodage
  crop: { aspectRatio: '16:9' },
  resize: { width: 1280 },
  output: { format: 'webp', webp: { quality: 85 } },
}, { timeoutMs: 5000 });

const { dataUrl } = await thumbhash(buf);   // un minuscule aperçu flouté pour <img>

#Un appel, de JavaScript à Rust et retour

La couche TypeScript convertit les options lisibles en ce qu'attend Rust (gravity: 'southEast' devient SouthEast) et branche l'AbortSignal. napi-rs passe le Buffer à Rust sous forme de tranche, sans le copier. Le gros du travail part sur un pool de threads bloquants, donc la boucle d'événements reste libre. Rust détecte le format grâce à ses octets magiques, décode à la plus petite taille possible, recadre, redimensionne, applique les effets, encode, et renvoie un Buffer, là encore sans copie.

Tracé du diagramme

#Les règles que ressent l'appelant

  • L'asynchrone ne bloque jamais la boucle d'événements. Le traitement d'image tourne sur un pool de threads. Les versions synchrones existent pour les scripts et les outils en ligne de commande.
  • Un seul transform() vaut mieux qu'une chaîne d'appels. Chaque appel séparé décode et réencode l'image. Un pipeline décode une fois et encode une fois.
  • Le recadrage passe en premier. Dans un pipeline, le recadrage s'applique avant le redimensionnement, donc chaque étape suivante touche moins de pixels. Le recadrage lui-même est une vue sur l'image décodée, pas une copie.
  • Les images énormes sont refusées, pas avalées. Tout ce qui dépasse 100 mégapixels est rejeté avant le décodage, pour qu'un seul fichier malveillant ne puisse pas épuiser la mémoire d'un serveur.
  • Délai et annulation sont intégrés. timeoutMs rejette la promesse côté Rust après le délai donné. Un AbortSignal permet à JavaScript d'annuler.
  • La bibliothèque dit ce qu'elle sait faire. codecBackend() indique si c'est la build native ou WebAssembly qui est chargée, et si le shrink-on-load, le WebP avec perte et le HEIC sont disponibles. Le code se branche sur des capacités, pas sur des noms de plateforme.

#D'où vient la vitesse

  • Métadonnées lues dans l'en-tête. Largeur, hauteur et format viennent des marqueurs JPEG, du bloc IHDR du PNG ou des blocs VP8 du WebP. Aucun pixel n'est décodé.
  • JPEG en SIMD. libjpeg-turbo choisit SSE2, AVX2 ou NEON à l'exécution.
  • Shrink-on-load. Quand la cible est bien plus petite, on demande au décodeur une image à 1/2, 1/4 ou 1/8 de sa taille : la mise à l'échelle de TurboJPEG pour le JPEG, celle de libwebp pour le WebP, libheif pour le HEIC. Une photo de 4000 px destinée à 200 px est décodée à 500 px.
  • Redimensionnement en plusieurs étapes. Pour une réduction de plus de 75 %, l'image est divisée par deux avec un filtre Box jusqu'à être à moins de 2× de la cible, puis terminée en Bilinear.
  • Filtres adaptatifs. Sans filtre précisé : Box au-delà d'une réduction de 4×, Bilinear de 2× à 4×, CatmullRom de 1,33× à 2×, Lanczos3 en dessous.
  • Chemins RGB et RGBA séparés. Une image sans canal alpha déplace 3 octets par pixel au lieu de 4.
  • Zéro copie à la frontière. Les Buffers d'entrée sont lus sur place, et les vecteurs de sortie deviennent des Buffers sans copie.

#Mesuré face à sharp

Apple M1 Pro, Bun 1.3.3, d'après la suite de benchmarks du dépôt (bun run benchmarks/final_comparison.ts).

OpérationimgkitsharpRatio
WebP, métadonnées0,004 ms3,4 ms950×
JPEG, métadonnées0,003 ms0,1 ms38×
50 opérations concurrentes62 ms160 ms2,6×
Pipeline de transformation12,2 ms19,1 ms1,6×
JPEG de 1 Mo → 800 px12,6 ms20,3 ms1,6×
Vignette, 200 px8,8 ms10,7 ms1,2×

Comment le lire : les ratios très élevés concernent les métadonnées, où imgkit ne lit qu'un en-tête. Sur le travail en pixels, l'avance est de 1,2× à 1,6×, et elle se réduit quand les images grandissent. Un WebP de 4000×3000 redimensionné à 400 px prend 32,4 ms contre 33,1 ms.

#Le HEIC, directement depuis un iPhone

Les iPhone enregistrent leurs photos en HEIC, et les binaires précompilés standard de sharp ne le lisent pas. imgkit décode le HEIC/HEIF via libheif, avec réduction au décodage : métadonnées d'en-tête en 0,1 ms, conversion complète HEIC → JPEG en 169 ms, redimensionnement à 800 px en 138 ms.

Le HEIC n'est livré que dans la build macOS ARM64. Depuis la 2.2.1, libheif et ses codecs sont compilés depuis les sources et liés statiquement, après que le binding a échoué à se charger sur des Mac qui n'avaient pas libheif.1.dylib. Pas de Homebrew, pas de bibliothèque système.

#Fonctionne là où il n'y a pas de binaire

Les binaires précompilés couvrent sept cibles : macOS ARM64 et x64, Linux x64 (glibc et musl) et ARM64, Windows x64 et ARM64. Ils s'installent comme dépendances optionnelles, donc personne ne compile rien. Depuis la 2.4.0, toute autre plateforme sous Node, comme FreeBSD ou Linux ARMv7, se replie sur WebAssembly au lieu de lever une erreur à l'import.

Tracé du diagramme

La build WebAssembly est compilée depuis le même code Rust, il n'y a donc pas de seconde implémentation qui dérive. Désactiver la feature cargo native-codecs remplace libjpeg-turbo et libwebp par des codecs en pur Rust, ce qui veut aussi dire que la crate se compile sans aucune chaîne d'outils C : ni nasm, ni cmake.

NatifWebAssembly
Codec JPEGlibjpeg-turbo, SIMDzune-jpeg, pur Rust
Shrink-on-loadouinon, décodage complet puis redimensionnement
WebP avec perte (quality)ouisans perte uniquement
HEIC/HEIFmacOS ARM64non
Travail asynchronepool de threadsthread appelant
timeoutMsappliquérejeté avec une erreur

Filtres de redimensionnement, recadrage, recadrage intelligent, composition, hachages, placeholders, couleurs, tenseurs et EXIF se comportent à l'identique des deux côtés, puisque c'est le même code.

#Trois décisions dans le repli

  • Un délai qui ne peut pas être respecté est refusé. Sous WebAssembly, le travail est synchrone en dessous, donc un délai ne pourrait pas l'interrompre. La build rejette timeoutMs avec une erreur explicite au lieu de l'ignorer en silence, parce qu'un délai ignoré donne à l'appelant une garantie qu'il n'a pas.
  • L'asynchrone fonctionne quand même. napi-rs exécute les exports asynchrones sur un runtime Tokio qui ne fonctionne pas sur cette cible WebAssembly. Une petite cale réimplémente chaque fonction asynchrone au-dessus de sa jumelle synchrone, donc await resize() se résout de la même façon.
  • Pas d'entrée navigateur, volontairement. Le module .wasm et les deux chargeurs sont dans le paquet, mais l'entrée navigateur générée par napi-rs réexporterait un paquet non publié et contournerait la couche TypeScript, donc les options ne seraient jamais converties. Plutôt que d'annoncer un export browser qui mène à quelque chose de cassé, il reste absent jusqu'à ce qu'une vraie entrée soit construite.

#Comment il est testé

  • La suite a grandi avec les fonctionnalités. 64 tests en 1.6.0, 111 en 1.8.0, 150 en 1.9.0, 176 en 2.0.0, plus une suite WebAssembly séparée.
  • Les tests Rust tournent sous les deux backends de codecs, natif et pur Rust, donc le repli est vérifié à la source.
  • La suite WebAssembly est hermétique. Les fixtures sont générées en mémoire par un petit encodeur PNG : pas de réseau, pas de fichiers binaires dans le dépôt, du .mjs simple qui tourne sur tout Node 18 ou plus récent.
  • Les installations sont testées comme un utilisateur installe. Le repli a été vérifié en installant l'archive empaquetée dans un projet vierge, et des versions précédentes ont été vérifiées avec Bun, npm, yarn et pnpm.

#Les bugs qui ont appris quelque chose

  • Bun pardonne, Node non. thumbhash() était cassé dans la build ESM sous Node : un require("zlib") à l'intérieur d'un module ES. Bun le tolère, donc une suite de tests qui ne tournait que sous Bun passait pendant que les utilisateurs de Node recevaient une erreur.
  • Un chemin testé n'est pas tous les chemins. Les WebP sans canal alpha échouaient dans un décodeur, parce que chaque test WebP passait des dimensions cibles et empruntait un autre décodeur.
  • La liaison dynamique casse sur la machine des autres. Le problème libheif décrit plus haut s'est terminé par une liaison statique.
  • Les noms comptent sur npm. Les paquets Windows ont été renommés imgkit-windows-x64 et imgkit-windows-arm64 après que les noms d'origine se sont heurtés à la détection de spam de npm.

#Pourquoi cette pile

  • Rust pour le cœur. La sûreté mémoire sans ramasse-miettes, et un accès direct aux meilleurs codecs : libjpeg-turbo, libwebp, libheif.
  • napi-rs pour la liaison. Un binaire précompilé par plateforme, des Buffers qui traversent la frontière sans copie, et la même chaîne d'outils construit la cible WebAssembly via emnapi.
  • fast_image_resize avec Rayon. Un redimensionnement SIMD réparti sur les cœurs, avec les filtres adaptatifs par-dessus.
  • Une couche TypeScript fine. Types, convertisseurs d'options, chargeur et cale WebAssembly. Tout ce qui touche à l'ergonomie JavaScript reste hors de Rust.
  • Bun pour le travail, Node comme cible. Bun gère l'installation, les builds, les tests et les benchmarks. Le paquet fonctionne dans les deux runtimes, et bunx imgkit-build gère le module natif pour les exécutables bun build --compile.

#Pas encore là

  • Navigateurs et runtimes edge. Les artefacts WebAssembly sont livrés, mais l'entrée navigateur n'est pas construite, et Cloudflare Workers et Deno Deploy ne sont pas testés.
  • Le décodage HEIC/HEIF n'existe que dans la build macOS ARM64, et HEIC et AVIF sont en lecture seule.
  • La build WebAssembly est plus lente : pas de shrink-on-load, JPEG scalaire, pas de travail hors du thread principal. Bun ne peut pas la charger, car son node:wasi n'a pas initialize() ; les utilisateurs de Bun ont de toute façon le module natif.
  • Compiler la cible WebAssembly demande emnapi 2.0 alpha, épinglé jusqu'à ce que la 2.x soit stable.

#Pour aller plus loin

La documentation complète couvre chaque fonction, les compromis WebAssembly et l'architecture plus en détail.

Ça vous a parlé ?

Conversation