Tutoriel d’annotation de distance Java : comment ajouter une mesure à une image avec GroupDocs

Dans ce guide complet, vous découvrirez comment ajouter une mesure aux images, aux PDF et à d’autres types de documents en utilisant GroupDocs.Annotation pour Java. Que vous construisiez un visualiseur CAD, un outil de révision architecturale ou une plateforme de documentation technique, les annotations de distance offrent à vos utilisateurs une règle claire et interactive sur laquelle ils peuvent compter. À la fin du tutoriel, vous disposerez d’une solution prête pour la production qui trace des mesures précises, personnalise leur apparence et s’intègre parfaitement à votre base de code Java existante.

Comment ajouter une mesure à une image en Java ?

Chargez le document cible avec Annotator, créez une DistanceAnnotation, configurez ses propriétés visuelles, ajoutez‑la à la page souhaitée, puis enregistrez le fichier. En seulement quatre lignes de code, vous obtenez une règle entièrement fonctionnelle qui peut être modifiée par les utilisateurs finaux dans n’importe quel visualiseur compatible. Cette approche fonctionne pour les PDF, les fichiers Word, les présentations PowerPoint, les feuilles Excel et les formats d’image courants tels que PNG, JPEG et TIFF.

Réponses rapides

  • Quelle est la façon la plus simple d’ajouter une mesure à une image en Java ? Utilisez la classe DistanceAnnotation de GroupDocs.Annotation.
  • Quels formats sont pris en charge ? PDF, Word, PowerPoint, Excel et les types d’image courants (PNG, JPEG, TIFF).
  • Ai‑je besoin d’une licence pour le développement ? Un essai gratuit ou une licence temporaire suffit pour les tests ; une licence commerciale est requise pour la production.
  • Puis‑je personnaliser l’apparence de la ligne de la règle ? Oui – vous pouvez définir la couleur, le style, l’épaisseur et l’opacité.
  • Comment éviter les fuites de mémoire ? Toujours libérer l’instance Annotator ou utiliser try‑with‑resources.

Qu’est‑ce que les annotations de distance (et pourquoi en avez‑vous besoin ?)

Les annotations de distance sont des éléments visuels interactifs qui affichent la longueur mesurée entre deux points d’un document. Elles fonctionnent comme des règles numériques que l’on peut placer n’importe où, déplacer et modifier en temps réel, offrant aux utilisateurs un retour visuel instantané sans calculs manuels.

Ces annotations apportent clarté visuelle, retour interactif et apparence professionnelle à tout document technique. Elles sont particulièrement utiles pour les dessins architecturaux, les schémas d’ingénierie, l’imagerie médicale et les plans d’étage immobiliers où des dimensions précises sont essentielles.

Bonnes pratiques de mesure de documents

Avant de commencer à coder, gardez à l’esprit ces pratiques éprouvées :

  1. Indexation des pages à partir de zéro – pageNumber = 0 fait référence à la première page, ce qui correspond au modèle interne de GroupDocs.Annotation.
  2. Couleurs à fort contraste – Choisissez des couleurs de règle qui se détachent du fond du document (par ex., jaune vif sur des schémas sombres).
  3. Réglage de l’opacité – Une opacité de 0.7 équilibre visibilité et détails sous‑jacent ; augmentez à 1.0 pour des mesures critiques.
  4. Regrouper les annotations liées – Utilisez des réponses ou des commentaires pour garder les discussions organisées autour d’une mesure spécifique.
  5. Libérer rapidement – Appelez toujours annotator.dispose() ou utilisez try‑with‑resources pour libérer la mémoire native, surtout lors du traitement de gros fichiers.

Prérequis : ce dont vous avez besoin avant de commencer

Exigences de l’environnement de développement

  • Java Development Kit (JDK) : version 8 ou supérieure (JDK 11+ recommandé).
  • Maven ou Gradle : les exemples utilisent Maven, mais les mêmes dépendances fonctionnent avec Gradle.
  • IDE : tout IDE Java (IntelliJ IDEA, Eclipse, VS Code, etc.) convient.

Prérequis de connaissances

Vous devriez déjà être à l’aise avec :

  • Les concepts de base de Java (classes, objets, méthodes).
  • L’ajout de bibliothèques externes via Maven/Gradle.
  • La gestion de base des fichiers I/O et des chemins.

Documents de test

Préparez quelques fichiers d’exemple :

  • Une ou plusieurs pages PDF.
  • Images PNG/JPEG/TIFF pour les tests raster.
  • Fichiers CAD optionnels si vous souhaitez expérimenter avec des dessins d’ingénierie.

Configuration de GroupDocs.Annotation pour Java

Intégrer GroupDocs.Annotation est un jeu d’enfant. Ci‑dessous, nous montrons les coordonnées Maven à ajouter à votre projet.

Intégration Maven

Ajoutez la configuration suivante à votre fichier pom.xml :

```xml
<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/annotation/java/</url>
   </repository>
</repositories>
<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-annotation</artifactId>
      <version>25.2</version>
   </dependency>
</dependencies>


### Comprendre les exigences de licence

GroupDocs.Annotation propose trois modèles de licence :

1. **Essai gratuit** – Idéal pour l’évaluation ; inclut toutes les fonctionnalités avec de légères limites d’utilisation.  
2. **Licence temporaire** – Supprime les restrictions d’essai pour le développement et les tests.  
3. **Licence commerciale** – Utilisation complète, prête pour la production, sans limites.

Commencez avec l’essai gratuit, puis passez à la version payante lorsque vous êtes prêt pour la production.

### Initialisation de base

La classe `Annotator` est le point d’entrée pour toutes les opérations d’annotation. Elle charge un document, fournit des API d’édition et écrit le résultat sur le disque.

```java
```java
import com.groupdocs.annotation.Annotator;

// Initialize annotator with the input file path
final Annotator annotator = new Annotator("YOUR_DOCUMENT_DIRECTORY/input.pdf");


**Astuce :** Enveloppez le `Annotator` dans un bloc try‑with‑resources ou appelez explicitement `dispose()` pour éviter les fuites de mémoire native.

## Guide d’implémentation étape par étape

Passons maintenant en revue un flux de travail complet et prêt pour la production afin d’ajouter des annotations de distance.

### Étape 1 : créer des réponses interactives (facultatif mais recommandé)

Les réponses permettent aux collaborateurs d’attacher des commentaires directement à une mesure, transformant une simple règle en fil de discussion.

```java
```java
import com.groupdocs.annotation.models.Reply;
import java.util.ArrayList;
import java.util.Calendar;

Reply reply1 = new Reply();
reply1.setComment("First comment");
reply1.setRepliedOn(Calendar.getInstance().getTime());

Reply reply2 = new Reply();
reply2.setComment("Second comment");
reply2.setRepliedOn(Calendar.getInstance().getTime());

ArrayList<Reply> replies = new ArrayList<>();
replies.add(reply1);
replies.add(reply2);


**Quand utiliser les réponses :** Dans les cycles de révision multi‑utilisateurs, lorsque vous devez expliquer pourquoi une dimension a été choisie ou demander des éclaircissements à un coéquipier.

### Étape 2 : configurer votre annotation de distance

La classe `DistanceAnnotation` est l’objet de niveau supérieur de GroupDocs.Annotation qui représente une mesure de règle. Vous pouvez personnaliser sa géométrie, son style visuel et le message attaché.

`Rectangle` définit la boîte englobante de l’annotation sur la page. `PenStyle` énumère les styles de ligne tels que plein, tiret et point.

```java
```java
import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.PenStyle;
import com.groupdocs.annotation.models.annotationmodels.DistanceAnnotation;

DistanceAnnotation distance = new DistanceAnnotation();
distance.setBox(new Rectangle(200, 150, 200, 30)); // Set the annotation's position and size
distance.setCreatedOn(Calendar.getInstance().getTime()); 
distance.setMessage("This is a distance annotation");
distance.setOpacity(0.7);
distance.setPageNumber(0); 
distance.setPenColor(65535);
distance.setPenStyle(PenStyle.DOT);
distance.setPenWidth((byte) 3);

distance.setReplies(replies); // Attach replies


**Options de configuration clés**  
- `setBox()` – Définit le rectangle englobant de l’annotation sur la page.  
- `setOpacity()` – Contrôle la transparence (`0.0` = invisible, `1.0` = totalement opaque).  
- `setPenColor()` – Couleur RVB pour la ligne de mesure.  
- `setPenStyle()` – Style de ligne (`DOT`, `DASH`, `SOLID`).  
- `setPenWidth()` – Épaisseur de la ligne en points.

### Étape 3 : appliquer l’annotation et enregistrer

Une fois l’annotation prête, ajoutez‑la au document et persistez les modifications.

```java
```java
annotator.add(distance);
annotator.save("YOUR_OUTPUT_DIRECTORY/output.pdf");
annotator.dispose();


**Important :** Appelez toujours `dispose()` après l’enregistrement, surtout lors du traitement de nombreux documents en lot.

## Exemple complet fonctionnel

En rassemblant tous les éléments, voici un exemple complet de bout en bout qui charge un PDF, ajoute une annotation de distance et enregistre le résultat.

```java
```java
import com.groupdocs.annotation.Annotator;
import com.groupdocs.annotation.models.Reply;
import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.PenStyle;
import com.groupdocs.annotation.models.annotationmodels.DistanceAnnotation;
import java.util.ArrayList;
import java.util.Calendar;

public class DistanceAnnotationExample {
    public static void main(String[] args) {
        try (Annotator annotator = new Annotator("input.pdf")) {
            // Create replies for the annotation
            ArrayList<Reply> replies = new ArrayList<>();
            Reply reply = new Reply();
            reply.setComment("Measurement verified by engineering team");
            reply.setRepliedOn(Calendar.getInstance().getTime());
            replies.add(reply);

            // Configure the distance annotation
            DistanceAnnotation distance = new DistanceAnnotation();
            distance.setBox(new Rectangle(100, 100, 300, 50));
            distance.setCreatedOn(Calendar.getInstance().getTime());
            distance.setMessage("Wall length: 12 feet");
            distance.setOpacity(0.8);
            distance.setPageNumber(0);
            distance.setPenColor(0xFF0000); // Red color
            distance.setPenStyle(PenStyle.SOLID);
            distance.setPenWidth((byte) 2);
            distance.setReplies(replies);

            // Add and save
            annotator.add(distance);
            annotator.save("output_with_distance_annotation.pdf");
            
            System.out.println("Distance annotation added successfully!");
        } catch (Exception e) {
            System.err.println("Error adding distance annotation: " + e.getMessage());
        }
    }
}


Exécutez le fragment, ouvrez le fichier de sortie dans n’importe quel visualiseur PDF qui prend en charge les annotations, et vous verrez une règle entièrement fonctionnelle prête à l’interaction.

## Cas d’utilisation courants et applications réelles

Comprendre où les annotations de distance brillent vous aide à décider comment les intégrer à votre produit.

### Documentation technique et manuels

- Mettre en évidence les dimensions des composants dans les guides d’assemblage.  
- Montrer les zones de dégagement dans les manuels d’installation.  
- Fournir des mesures de référence rapides pour les listes de contrôle de la qualité.

### Projets architecturaux et d’ingénierie

- Afficher les tailles des pièces sur les plans d’étage.  
- Indiquer l’espacement des éléments structurels.  
- Marquer les distances des lignes d’utilité et les dégagements de sécurité.

### Applications médicales et scientifiques

- Mesurer les structures anatomiques dans les images radiologiques.  
- Ajouter des barres d’échelle aux lames de microscopie.  
- Documenter les dimensions des spécimens dans les rapports de recherche.

### Immobilier et gestion de biens

- Visualiser les limites de lot et les lignes de propriété.  
- Montrer les dimensions des pièces pour les annonces.  
- Indiquer les tailles des places de parking et les mesures d’aménagement paysager.

## Résolution des problèmes courants

Même un exemple bien rédigé peut rencontrer des problèmes. Voici les problèmes les plus fréquents et comment les résoudre.

### Problème : « Fichier non trouvé » ou problèmes de chemin

**Symptômes :** Une exception est levée lors de la création du `Annotator`.  

**Solution :** Utilisez un chemin absolu pendant le développement, vérifiez que le fichier existe et assurez‑vous que le processus dispose des permissions de lecture.

```java
```java
// Better path handling
String inputPath = new File("documents/input.pdf").getAbsolutePath();
final Annotator annotator = new Annotator(inputPath);


### Problème : annotation non visible

**Symptômes :** Le code s’exécute sans erreur, mais aucune règle n’apparaît.  

**Causes courantes :** Index de page incorrect (rappelez‑vous que les pages commencent à 0), annotation placée en dehors du canevas visible, ou opacité réglée trop basse.

**Correctifs rapides :**

```java
```java
distance.setPageNumber(0); // First page
distance.setOpacity(1.0);  // Fully opaque
distance.setBox(new Rectangle(50, 50, 200, 30)); // Visible position


### Problème : problèmes de mémoire avec de gros documents

**Symptômes :** `OutOfMemoryError` ou performances lentes sur des fichiers de plusieurs centaines de pages.  

**Solutions :**  
- Libérez chaque instance `Annotator` dès que vous avez terminé.  
- Traitez les documents séquentiellement plutôt que de les charger tous en même temps.  
- Augmentez le tas JVM (`-Xmx4g` ou plus) pour des entrées très volumineuses.

```java
```java
// Good practice - use try-with-resources
try (Annotator annotator = new Annotator("large-document.pdf")) {
    // Your annotation code here
} // Automatic disposal


### Problème : erreurs liées à la licence

**Symptômes :** Avertissements concernant les limites de l’essai ou des échecs de validation de licence.  

**Solutions :**  
- Confirmez que le chemin du fichier de licence est correct et que le fichier est lisible.  
- Assurez‑vous que la version de la licence correspond à la version de la bibliothèque GroupDocs.Annotation que vous utilisez.  
- Vérifiez qu’une licence temporaire n’est pas expirée.

## Conseils d’optimisation des performances

Lorsque vous passez d’un prototype à la production, gardez à l’esprit ces considérations de performance.

### Meilleures pratiques de gestion de la mémoire

- **Toujours libérer** : privilégiez try‑with‑resources ou `dispose()` explicite.  
- **Opérations par lots** : regroupez plusieurs modifications d’annotation dans une seule session `Annotator` pour réduire la surcharge.  
- **Profilage** : utilisez des profileurs Java (VisualVM, YourKit) pour surveiller l’utilisation de la mémoire native.

### Optimisation du traitement des fichiers

- **Mettre en cache les documents fréquemment accédés** en mémoire lorsqu’ils sont en lecture seule.  
- **Privilégier le PDF** aux images haute résolution pour un rendu plus rapide ; les PDF sont en moyenne 30‑40 % plus petits pour le même contenu visuel.  
- **Ajuster la résolution des images** : réduire les images sources à un maximum de 150 DPI sauf si une fidélité supérieure est requise.

### Considérations de traitement concurrent

Si votre service traite de nombreux fichiers en parallèle, suivez ces règles :

```java
```java
// Example of efficient batch processing
public void processMultipleDocuments(List<String> filePaths) {
    for (String path : filePaths) {
        try (Annotator annotator = new Annotator(path)) {
            // Add multiple annotations per document
            addDistanceAnnotation(annotator, config1);
            addDistanceAnnotation(annotator, config2);
            // Save once with all annotations
            annotator.save(getOutputPath(path));
        }
    }
}


- Chaque thread doit instancier son propre `Annotator`.  
- Utilisez un pool de threads limité pour éviter d’épuiser les ressources système.  
- Surveillez l’utilisation du CPU et du tas sous charge ; mise à l’échelle horizontale si nécessaire.

## Options de configuration avancées

Une fois les bases maîtrisées, explorez ces fonctionnalités avancées pour affiner vos annotations.

### Options de style personnalisées

```java
```java
// Advanced pen styling
distance.setPenStyle(PenStyle.DASH_DOT);
distance.setPenWidth((byte) 4);
distance.setPenColor(0x00FF00); // Hex color codes work too

// Custom opacity for different emphasis levels
distance.setOpacity(0.6); // Subtle background measurements
// vs
distance.setOpacity(1.0); // Prominent foreground measurements


Vous pouvez définir un objet `Pen` personnalisé, appliquer des remplissages en dégradé, ou même intégrer des marqueurs SVG aux extrémités de la ligne de la règle.

### Positionnement dynamique

```java
```java
// Calculate position based on document dimensions or content
Rectangle dynamicBox = calculateOptimalPosition(documentWidth, documentHeight);
distance.setBox(dynamicBox);


Exploitez les coordonnées relatives à la page afin que l’annotation se repositionne automatiquement lorsque le document est zoomé ou pivoté.

### Annotations conditionnelles

```java
```java
// Add annotations based on document content or user preferences
if (document.getType() == DocumentType.ARCHITECTURAL_PLAN) {
    distance.setMessage("Room dimension");
    distance.setPenStyle(PenStyle.SOLID);
} else if (document.getType() == DocumentType.ENGINEERING_DRAWING) {
    distance.setMessage("Component spacing");
    distance.setPenStyle(PenStyle.DOT);
}


Ajoutez une logique qui ne crée une annotation de distance que lorsqu’une certaine condition est remplie (par ex., lorsqu’un composant dépasse un seuil de tolérance).

## Intégration avec d’autres systèmes

### Intégration de base de données

`AnnotationRecord` est un modèle de données personnalisé pour persister les métadonnées d’annotation dans une base de données.

```java
```java
// Save annotation details to database
AnnotationRecord record = new AnnotationRecord();
record.setDocumentId(documentId);
record.setAnnotationType("distance");
record.setMeasurement(distance.getMessage());
record.setCreatedDate(distance.getCreatedOn());


Stockez les métadonnées d’annotation (auteur, horodatage, valeur de mesure) dans une base de données relationnelle pour les rapports et la recherche.

### Intégration d’application web

`DistanceAnnotationRequest` est un DTO qui transporte les paramètres d’annotation du client vers le serveur.

```java
```java
@PostMapping("/documents/{id}/annotations/distance")
public ResponseEntity<String> addDistanceAnnotation(
    @PathVariable String id,
    @RequestBody DistanceAnnotationRequest request) {
    // Process the annotation request
    // Return success/failure response
}


Exposez un point d’accès REST qui accepte un fichier, ajoute une annotation de distance basée sur la charge JSON, et renvoie le document annoté.

### Intégration de stockage cloud

```java
```java
// Download from cloud, process, upload result
byte[] documentBytes = cloudStorageService.download(documentPath);
// Process with GroupDocs.Annotation
byte[] annotatedDocument = processAnnotations(documentBytes);
cloudStorageService.upload(outputPath, annotatedDocument);


Lisez et écrivez des fichiers directement depuis AWS S3, Azure Blob Storage ou Google Cloud Storage à l’aide des SDK respectifs, puis transmettez les flux à `Annotator`.

## Questions fréquemment posées

**Q : Quels formats de documents prennent en charge les annotations de distance ?**  
R : GroupDocs.Annotation prend en charge les PDF, les documents Word, les présentations PowerPoint, les feuilles de calcul Excel et les formats d’image courants (PNG, JPEG, TIFF, BMP). La fonctionnalité fonctionne de manière cohérente sur les plus de 50 formats pris en charge.

**Q : Puis‑je personnaliser l’apparence des lignes de mesure ?**  
R : Absolument ! Vous avez un contrôle total sur la couleur du stylo, le style de ligne (plein, pointillé, tireté), l’épaisseur et l’opacité. Vous pouvez également définir des symboles d’extrémité personnalisés pour des normes d’ingénierie spécialisées.

**Q : Comment gérer les mesures dans différentes unités ?**  
R : L’annotation elle‑même affiche le texte que vous définissez dans la propriété `message`. Effectuez toute conversion d’unité (par ex., pouces ↔ millimètres) dans votre code Java avant d’assigner le message.

**Q : Les utilisateurs peuvent‑ils interagir avec les annotations de distance après leur ajout ?**  
R : Oui. Dans les visualiseurs compatibles (GroupDocs.Viewer, Adobe Acrobat ou votre propre visualiseur web), les utilisateurs peuvent cliquer, faire glisser et modifier la règle. Les réponses et commentaires restent attachés à la mesure pour une révision collaborative.

**Q : Quel est l’impact sur les performances lors de l’ajout de nombreuses annotations ?**  
R : Ajouter jusqu’à plusieurs centaines d’annotations par document a un impact négligeable (< 5 % de surcharge CPU). Lorsque vous dépassez 1 000 annotations, les temps de chargement peuvent augmenter légèrement, mais la bibliothèque reste stable et réactive.

## Conclusion et prochaines étapes

Vous disposez maintenant d’une feuille de route complète et prête pour la production pour **comment ajouter une mesure** aux images et autres documents en Java avec GroupDocs.Annotation. En exploitant les annotations de distance, vous pouvez transformer des dessins statiques en actifs interactifs et riches en données qui améliorent la collaboration et réduisent les erreurs.

**Points clés**

- Les annotations de distance offrent des mesures précises et visuelles sur plus de 50 formats de fichiers.  
- L’implémentation est concise : charger, configurer, ajouter, enregistrer.  
- Les performances sont robustes pour les documents de taille moyenne ; suivez les conseils de gestion de la mémoire pour les gros fichiers.  
- Les points d’intégration (BD, REST, cloud) vous permettent d’intégrer les annotations dans n’importe quel flux de travail.

### Étapes suivantes recommandées

1. **Prototype** : clonez l’exemple complet, exécutez‑le avec vos propres PDF ou images, et vérifiez que la règle apparaît comme prévu.  
2. **Explorez d’autres types d’annotation** : les annotations de surlignage, de texte et de tampon peuvent compléter les mesures de distance.  
3. **Construisez une interface utilisateur** : concevez une interface glisser‑déposer qui permette aux utilisateurs finaux de placer des règles directement dans le navigateur ou le client de bureau.  
4. **Planifiez l’évolutivité** : si vous prévoyez des milliers d’utilisateurs concurrents, implémentez une stratégie de pool de threads et surveillez l’utilisation du tas comme décrit dans la section performance.  

---

**Dernière mise à jour** : 2026-06-16  
**Testé avec** : GroupDocs.Annotation 25.2 for Java  
**Auteur** : GroupDocs  

**Ressources associées**  
- [GroupDocs.Annotation Documentation](https://docs.groupdocs.com/annotation/java/) - Comprehensive API documentation  
- [API Reference](https://reference.groupdocs.com/annotation/java/) - Detailed method and class references  
- [Download Page](https://releases.groupdocs.com/annotation/java/) - Latest versions and release notes  
- [Support Forum](https://forum.groupdocs.com/c/annotation/) - Community support and discussions  
- [Purchase Options](https://purchase.groupdocs.com/buy) - Commercial licensing information  
- [Free Trial](https://releases.groupdocs.com/annotation/java/) - Try before you buy  
- [Temporary License](https://purchase.groupdocs.com/temporary-license/) - Extended evaluation license  

## Tutoriels associés

- [Comment ajouter une flèche à un PDF avec Java – Tutoriel complet et meilleures pratiques](/annotation/java/graphical-annotations/add-arrow-annotations-java-groupdocs/)  
- [Annotation d’image PDF Java – Tutoriel complet GroupDocs](/annotation/java/image-annotations/annotate-pdfs-java-groupdocs-image-annotations/)  
- [Modifier les annotations PDF Java – Tutoriel complet GroupDocs](/annotation/java/annotation-management/groupdocs-annotation-java-modify-pdf-annotations/)