Java 거리 주석 튜토리얼: GroupDocs로 이미지에 측정 추가하기

이 포괄적인 가이드에서는 Java용 GroupDocs.Annotation을 사용하여 이미지, PDF 및 기타 문서 유형에 측정 추가 방법을 배울 수 있습니다. CAD 뷰어, 건축 검토 도구, 혹은 기술 문서 플랫폼을 구축하든, 거리 주석은 사용자에게 신뢰할 수 있는 명확하고 인터랙티브한 눈금을 제공합니다. 튜토리얼이 끝날 때쯤이면 정밀한 측정을 그리며 외관을 커스터마이징하고 기존 Java 코드베이스와 원활히 통합되는 프로덕션 준비 솔루션을 갖추게 됩니다.

Java에서 이미지에 측정 추가하는 방법?

Annotator로 대상 문서를 로드하고, DistanceAnnotation을 생성한 뒤 시각적 속성을 설정하고 원하는 페이지에 추가한 후 파일을 저장합니다. 단 네 줄의 코드만으로도 모든 호환 뷰어에서 최종 사용자가 편집할 수 있는 완전한 기능의 눈금을 얻을 수 있습니다. 이 방법은 PDF, Word 파일, PowerPoint 프레젠테이션, Excel 시트 및 PNG, JPEG, TIFF와 같은 일반 이미지 형식에서도 작동합니다.

빠른 답변

• Java에서 이미지에 측정을 추가하는 가장 쉬운 방법은 무엇인가요? GroupDocs.Annotation의 DistanceAnnotation 클래스를 사용하십시오.
• 지원되는 형식은 무엇인가요? PDF, Word, PowerPoint, Excel 및 일반 이미지 유형(PNG, JPEG, TIFF).
• 개발에 라이선스가 필요합니까? 테스트용으로는 무료 체험 또는 임시 라이선스로 충분하지만, 프로덕션에서는 상용 라이선스가 필요합니다.
• 눈금선의 외관을 커스터마이즈할 수 있나요? 예 – 색상, 스타일, 두께 및 투명도를 설정할 수 있습니다.
• 메모리 누수를 방지하려면 어떻게 해야 하나요? 항상 Annotator 인스턴스를 해제하거나 try‑with‑resources를 사용하십시오.

거리 주석이란? (그리고 왜 필요한가?)

거리 주석은 문서 내 두 지점 사이의 측정 길이를 표시하는 인터랙티브한 시각 요소입니다. 어디에든 배치하고 끌어다 놓으며 실시간으로 편집할 수 있는 디지털 눈금자와 같으며, 사용자는 수동 계산 없이 즉각적인 시각 피드백을 얻을 수 있습니다.

이러한 주석은 시각적 명확성, 인터랙티브 피드백, 그리고 전문적인 외관을 모든 기술 문서에 제공합니다. 정확한 치수가 중요한 건축 도면, 엔지니어링 설계도, 의료 영상 및 부동산 평면도 등에 특히 유용합니다.

문서 측정 모범 사례

코딩을 시작하기 전에 다음 검증된 관행을 기억하십시오:

1. 0 기반 페이지 인덱싱 – pageNumber = 0은 첫 번째 페이지를 의미하며, GroupDocs.Annotation의 내부 모델과 일치합니다.
2. 고대비 색상 – 문서 배경과 대비되는 눈금자 색상을 선택하십시오(예: 어두운 도면에 밝은 노란색).
3. 투명도 조정 – 0.7의 투명도는 가시성과 배경 세부 정보를 균형 있게 하며, 중요한 측정에는 1.0으로 높일 수 있습니다.
4. 관련 주석 그룹화 – 특정 측정에 대한 토론을 정리하려면 답글이나 댓글을 사용하십시오.
5. 즉시 해제 – 특히 대용량 파일을 처리할 때는 항상 annotator.dispose()를 호출하거나 try‑with‑resources를 사용하여 네이티브 메모리를 해제하십시오.

사전 준비 사항: 시작하기 전에 필요한 것

개발 환경 요구 사항

• Java Development Kit (JDK): 버전 8 이상 (JDK 11+ 권장).
• Maven 또는 Gradle: 예제는 Maven을 사용하지만 동일한 의존성을 Gradle에서도 사용할 수 있습니다.
• IDE: IntelliJ IDEA, Eclipse, VS Code 등 어떤 Java IDE든 상관없습니다.

지식 사전 조건

다음에 익숙해야 합니다:

• 핵심 Java 개념(클래스, 객체, 메서드).
• Maven/Gradle을 통한 외부 라이브러리 추가.
• 기본 파일 I/O 및 경로 처리.

테스트 문서

몇 개의 샘플 파일을 준비하십시오:

• 하나 이상의 PDF 페이지.
• 래스터 기반 테스트를 위한 PNG/JPEG/TIFF 이미지.
• 엔지니어링 도면을 실험하고 싶다면 선택적인 CAD 파일.

Java용 GroupDocs.Annotation 설정

GroupDocs.Annotation 통합은 매우 간단합니다. 아래에 프로젝트에 추가해야 할 Maven 좌표를 보여드립니다.

Maven 통합

pom.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>

라이선스 요구 사항 이해

GroupDocs.Annotation은 세 가지 라이선스 모델을 제공합니다:

1. 무료 체험 – 평가에 이상적이며, 약간의 사용 제한이 있는 모든 기능을 포함합니다.
2. 임시 라이선스 – 개발 및 테스트를 위한 체험 제한을 해제합니다.
3. 상용 라이선스 – 제한 없이 전체 기능을 제공하며 프로덕션에 적합합니다.

먼저 무료 체험으로 시작하고, 프로덕션 준비가 되면 업그레이드하십시오.

기본 초기화

Annotator 클래스는 모든 주석 작업의 진입점입니다. 문서를 로드하고, 편집 API를 제공하며, 결과를 디스크에 저장합니다.

import com.groupdocs.annotation.Annotator;

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

Pro Tip: Annotator를 try‑with‑resources 블록으로 감싸거나 명시적으로 dispose()를 호출하여 네이티브 메모리 누수를 방지하십시오.

단계별 구현 가이드

이제 거리 주석을 추가하기 위한 완전한 프로덕션 준비 워크플로우를 단계별로 살펴보겠습니다.

단계 1: 인터랙티브 답글 만들기 (선택 사항이지만 권장)

답글을 사용하면 협업자가 측정에 직접 댓글을 달아 간단한 눈금을 토론 스레드로 전환할 수 있습니다.

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);

답글을 사용할 때: 다중 사용자 검토 단계에서 치수를 선택한 이유를 설명하거나 팀원에게 명확성을 요청해야 할 경우.

단계 2: 거리 주석 구성

DistanceAnnotation 클래스는 눈금 측정을 나타내는 GroupDocs.Annotation의 최상위 객체입니다. 기하학, 시각 스타일 및 첨부 메시지를 커스터마이즈할 수 있습니다.

Rectangle은 페이지에서 주석의 경계 상자를 정의합니다. PenStyle은 실선, 대시, 점 등 라인 스타일을 열거합니다.

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

핵심 구성 옵션

• setBox() – 페이지에서 주석의 경계 사각형을 설정합니다.
• setOpacity() – 투명도를 제어합니다(0.0 = 투명, 1.0 = 완전 불투명).
• setPenColor() – 측정 라인의 RGB 색상.
• setPenStyle() – 라인 스타일(DOT, DASH, SOLID).
• setPenWidth() – 포인트 단위의 라인 두께.

단계 3: 주석 적용 및 저장

주석이 준비되면 문서에 추가하고 변경 사항을 저장하십시오.

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

중요: 저장 후에는 항상 dispose()를 호출하십시오. 특히 배치 작업에서 다수의 문서를 처리할 때 필요합니다.

전체 작업 예제

모든 것을 종합한 전체 엔드‑투‑엔드 예제로, PDF를 로드하고 거리 주석을 추가한 뒤 결과를 저장합니다.

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());
        }
    }
}

코드를 실행하고, 주석을 지원하는 PDF 뷰어에서 출력 파일을 열면 인터랙션이 가능한 완전한 눈금을 확인할 수 있습니다.

일반적인 사용 사례 및 실제 적용

거리 주석이 빛을 발하는 영역을 이해하면 제품에 어떻게 삽입할지 결정하는 데 도움이 됩니다.

기술 문서 및 매뉴얼

• 조립 가이드에서 부품 치수를 강조합니다.
• 설치 매뉴얼에서 여유 공간을 표시합니다.
• 품질 관리 체크리스트를 위한 빠른 참조 측정을 제공합니다.

건축 및 엔지니어링 프로젝트

• 평면도에 방 크기를 표시합니다.
• 구조 요소 간 간격을 표시합니다.
• 설비 라인 거리 및 안전 여유를 표시합니다.

의료 및 과학 응용

• 방사선 이미지에서 해부학적 구조를 측정합니다.
• 현미경 슬라이드에 스케일 바를 추가합니다.
• 연구 보고서에 표본 치수를 기록합니다.

부동산 및 자산 관리

• 토지 경계와 부동산 라인을 시각화합니다.
• 매물에 방 치수를 표시합니다.
• 주차 공간 크기 및 조경 측정을 표시합니다.

일반적인 문제 해결

잘 작성된 예제라도 문제가 발생할 수 있습니다. 아래는 가장 흔한 문제와 해결 방법입니다.

문제: “파일을 찾을 수 없음” 또는 경로 문제

증상: Annotator를 생성할 때 예외가 발생합니다.
해결책: 개발 중에는 절대 경로를 사용하고, 파일이 존재하는지 확인하며, 프로세스에 읽기 권한이 있는지 확인하십시오.

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

문제: 주석이 보이지 않음

증상: 코드가 오류 없이 실행되지만 눈금이 나타나지 않습니다.
일반 원인: 잘못된 페이지 인덱스(페이지는 0부터 시작), 주석이 보이는 캔버스 밖에 배치, 혹은 투명도가 너무 낮음.

빠른 해결:

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

문제: 대용량 문서에서 메모리 문제

증상: 수백 페이지 파일에서 OutOfMemoryError 또는 성능 저하가 발생합니다.
해결책:

• 작업이 끝나면 각 Annotator 인스턴스를 즉시 해제합니다.
• 모든 파일을 한 번에 로드하지 말고 순차적으로 처리합니다.
• 매우 큰 입력에 대해 JVM 힙을 늘립니다(-Xmx4g 이상).

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

문제: 라이선스 관련 오류

증상: 체험 제한 또는 라이선스 검증 실패에 대한 경고가 표시됩니다.
해결책:

• 라이선스 파일 경로가 정확하고 파일을 읽을 수 있는지 확인합니다.
• 사용 중인 GroupDocs.Annotation 라이브러리 버전과 라이선스 버전이 일치하는지 확인합니다.
• 임시 라이선스가 만료되지 않았는지 확인합니다.

성능 최적화 팁

프로토타입에서 프로덕션으로 전환할 때 다음 성능 고려 사항을 기억하십시오.

메모리 관리 모범 사례

• 항상 해제: try‑with‑resources를 사용하거나 명시적으로 dispose()를 호출하십시오.
• 배치 작업: 하나의 Annotator 세션에서 여러 주석 변경을 그룹화하여 오버헤드를 줄이십시오.
• 프로파일링: Java 프로파일러(VisualVM, YourKit)를 사용해 네이티브 메모리 사용량을 모니터링하십시오.

파일 처리 최적화

• 자주 접근하는 문서를 읽기 전용으로 메모리에 캐시하십시오.
• 고해상도 이미지보다 PDF를 선호하면 렌더링이 빠릅니다; 동일한 시각 콘텐츠에 대해 PDF가 평균 30‑40 % 작습니다.
• 이미지 해상도 조정: 높은 품질이 필요하지 않은 경우 소스 이미지를 최대 150 DPI로 다운스케일하십시오.

동시 처리 고려 사항

서비스가 다수의 파일을 병렬로 처리한다면 다음 규칙을 따르십시오:

// 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));
        }
    }
}

• 각 스레드는 자체 Annotator 인스턴스를 생성해야 합니다.
• 시스템 자원을 고갈시키지 않도록 제한된 스레드 풀을 사용하십시오.
• 부하 시 CPU와 힙 사용량을 모니터링하고 필요 시 수평 확장을 고려하십시오.

고급 구성 옵션

기본을 마스터했다면, 주석을 세밀하게 조정할 수 있는 고급 기능을 살펴보십시오.

사용자 정의 스타일 옵션

// 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

맞춤 Pen 객체를 정의하고, 그라디언트 채우기를 적용하거나 눈금선 끝에 SVG 마커를 삽입할 수도 있습니다.

동적 위치 지정

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

페이지 상대 좌표를 활용하면 문서가 확대되거나 회전될 때 주석이 자동으로 재배치됩니다.

조건부 주석

// 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);
}

특정 조건이 충족될 때만 거리 주석을 생성하도록 로직을 추가하십시오(예: 부품이 허용 오차를 초과할 때).

다른 시스템과의 통합

거리 주석은 독립적인 것이 아니라, 보다 넓은 문서 관리 생태계에 자연스럽게 통합됩니다.

데이터베이스 통합

AnnotationRecord는 데이터베이스에 주석 메타데이터를 저장하기 위한 맞춤 데이터 모델입니다.

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

주석 메타데이터(작성자, 타임스탬프, 측정값)를 관계형 데이터베이스에 저장하여 보고 및 검색에 활용하십시오.

웹 애플리케이션 통합

DistanceAnnotationRequest는 클라이언트에서 서버로 주석 매개변수를 전달하는 DTO입니다.

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

파일을 받아 JSON 페이로드를 기반으로 거리 주석을 추가하고 주석이 적용된 문서를 반환하는 REST 엔드포인트를 노출하십시오.

클라우드 스토리지 통합

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

해당 SDK를 사용해 AWS S3, Azure Blob Storage, Google Cloud Storage에서 파일을 직접 읽고 쓰고, 스트림을 Annotator에 전달하십시오.

자주 묻는 질문

Q: 거리 주석을 지원하는 문서 형식은 무엇인가요?
A: GroupDocs.Annotation은 PDF, Word 문서, PowerPoint 프레젠테이션, Excel 스프레드시트 및 일반 이미지 형식(PNG, JPEG, TIFF, BMP)을 지원합니다. 이 기능은 50개 이상의 지원 형식 전반에 걸쳐 일관되게 작동합니다.

Q: 측정 라인의 외관을 커스터마이즈할 수 있나요?
A: 물론입니다! 펜 색상, 라인 스타일(실선, 점선, 대시), 라인 두께 및 투명도를 완전히 제어할 수 있습니다. 또한 특수 엔지니어링 표준을 위한 맞춤 끝 캡 기호도 정의할 수 있습니다.

Q: 다른 단위의 측정을 어떻게 처리하나요?
A: 주석 자체는 message 속성에 설정한 텍스트를 표시합니다. 메시지를 할당하기 전에 Java 코드에서 단위 변환(예: 인치 ↔ 밀리미터)을 수행하십시오.

Q: 주석이 추가된 후에도 사용자가 거리 주석과 상호작용할 수 있나요?
A: 예. 호환 뷰어(GroupDocs.Viewer, Adobe Acrobat 또는 자체 웹 뷰어)에서 사용자는 눈금을 클릭, 드래그 및 편집할 수 있습니다. 답글과 댓글은 협업 검토를 위해 측정에 계속 연결됩니다.

Q: 많은 주석을 추가하면 성능에 어떤 영향을 미치나요?
A: 문서당 수백 개의 주석을 추가해도 영향이 거의 없으며(CPU 오버헤드 < 5 %), 1,000개를 초과하면 로딩 시간이 다소 증가할 수 있지만 라이브러리는 여전히 안정적이고 반응성이 좋습니다.

결론 및 다음 단계

이제 Java에서 GroupDocs.Annotation을 사용해 이미지 및 기타 문서에 측정 추가하는 완전한 프로덕션 준비 로드맵을 갖추었습니다. 거리 주석을 활용하면 정적 도면을 인터랙티브하고 데이터가 풍부한 자산으로 전환하여 협업을 개선하고 오류를 줄일 수 있습니다.

핵심 요약

• 거리 주석은 50개 이상의 파일 형식에서 정밀하고 시각적인 측정을 제공합니다.
• 구현이 간결합니다: 로드, 구성, 추가, 저장.
• 중간 규모 문서에 대해 성능이 견고하며, 대용량 파일의 경우 메모리 관리 팁을 따르십시오.
• 통합 포인트(DB, REST, 클라우드)를 통해 주석을 모든 워크플로에 삽입할 수 있습니다.

권장 다음 단계

1. 프로토타입: 전체 예제를 복제하고 자체 PDF 또는 이미지에 실행하여 눈금이 예상대로 나타나는지 확인하십시오.
2. 다른 주석 유형 탐색: 하이라이트, 텍스트, 스탬프 주석은 거리 측정을 보완할 수 있습니다.
3. UI 구축: 사용자가 브라우저나 데스크톱 클라이언트에서 직접 눈금을 끌어다 놓을 수 있는 인터페이스를 설계하십시오.
4. 규모 계획: 수천 명의 동시 사용자를 예상한다면, 스레드 풀 전략을 구현하고 성능 섹션에 설명된 대로 힙 사용량을 모니터링하십시오.

마지막 업데이트: 2026-06-16
테스트 환경: GroupDocs.Annotation 25.2 for Java
작성자: GroupDocs

관련 리소스:

• GroupDocs.Annotation 문서 - Comprehensive API documentation
• API 레퍼런스 - Detailed method and class references
• 다운로드 페이지 - Latest versions and release notes
• 지원 포럼 - Community support and discussions
• 구매 옵션 - Commercial licensing information
• 무료 체험 - Try before you buy
• 임시 라이선스 - Extended evaluation license

관련 튜토리얼

• Java로 PDF에 화살표 추가하기 – 완전 튜토리얼 및 모범 사례
• Java PDF 이미지 주석 – 완전 GroupDocs 튜토리얼
• PDF 주석 편집 Java – 완전 GroupDocs 튜토리얼