Recadrer des images en JavaScript avec des coordonnées exactes

Un outil de recadrage JavaScript remplit deux fonctions : aider une personne à choisir une région et décrire cette région sans ambiguïté. La confusion entre les pixels de l’aperçu, les coordonnées mises à l’échelle par CSS et les pixels source est la cause la plus fréquente des recadrages incorrects.

L’essentiel

• Évitez de décoder à répétition de très grandes images sur les appareils disposant de peu de mémoire.
• Validez à nouveau les coordonnées et les dimensions minimales sur le serveur.

function normalizeCrop(crop, sourceWidth, sourceHeight) {
  return {
    x: crop.x / sourceWidth,
    y: crop.y / sourceHeight,
    width: crop.width / sourceWidth,
    height: crop.height / sourceHeight,
  }
}

function cropToSourcePixels(crop, sourceWidth, sourceHeight) {
  return {
    left: Math.round(crop.x * sourceWidth),
    top: Math.round(crop.y * sourceHeight),
    right: Math.round((crop.x + crop.width) * sourceWidth),
    bottom: Math.round((crop.y + crop.height) * sourceHeight),
  }
}

function renderCrop(image, crop, maxDimension = 1024) {
  const width = crop.right - crop.left
  const height = crop.bottom - crop.top
  if (![width, height, maxDimension].every((value) => Number.isFinite(value) && value > 0)) {
    throw new Error('Crop dimensions must be finite and positive')
  }
  const scale = Math.min(1, maxDimension / Math.max(width, height))
  const canvas = document.createElement('canvas')
  canvas.width = Math.max(1, Math.round(width * scale))
  canvas.height = Math.max(1, Math.round(height * scale))
  const context = canvas.getContext('2d')
  if (context == null) throw new Error('2D canvas is unavailable')

  context.drawImage(
    image,
    crop.left,
    crop.top,
    width,
    height,
    0,
    0,
    canvas.width,
    canvas.height,
  )

  return new Promise((resolve, reject) => {
    canvas.toBlob((blob) => {
      if (blob == null) reject(new Error('The browser could not encode the crop'))
      // Browsers fall back to image/png when the requested type is unsupported
      else if (blob.type !== 'image/webp') reject(new Error('Encoder fell back to ' + blob.type))
      else resolve(blob)
    }, 'image/webp', 0.86)
  })
}

Détails techniques à connaître

• naturalWidth et naturalHeight décrivent les dimensions de l’image décodée, tandis que clientWidth et clientHeight décrivent la boîte CSS. Les coordonnées de recadrage doivent être converties entre ces espaces.
• Les images issues d’appareils photo peuvent contenir des métadonnées d’orientation qui modifient la largeur, la hauteur et les axes visibles sans changer l’ordre des pixels stockés. L’orientation doit donc être normalisée avant les calculs de coordonnées.
• Les URL de Blob évitent le surcoût de taille d’environ un tiers des URL de données en base64, mais chaque URL conserve le Blob sous-jacent jusqu’à l’appel de URL.revokeObjectURL ou au déchargement du document.
• L’export par canvas peut modifier les profils colorimétriques, les métadonnées, l’animation et la qualité d’encodage, ce qui constitue une raison supplémentaire de considérer le résultat du navigateur comme un aperçu plutôt que comme l’image maîtresse.
• Les coordonnées du pointeur sont relatives à la zone d’affichage jusqu’à leur conversion prenant en compte le rectangle englobant de l’élément, le défilement, le zoom et les éventuelles transformations CSS appliquées.
• Les très grandes images décodées peuvent dépasser les limites de canvas sur mobile, même lorsque le fichier téléversé compressé est petit. Les dimensions de l’aperçu et le nombre de pixels source nécessitent donc des limites distinctes.

Une approche pratique

Périmètre architectural

Le canvas du navigateur est utile pour les aperçus interactifs, mais il consomme de la mémoire côté client et ne garantit pas un encodage identique sur tous les appareils. Ne confiez pas à un téléphone la génération de tous les dérivés utilisés en production.