이미지 주석 추가: 펜, 화살표, 원형으로 이미지 마크업하기

이 강의에서 배우는 것

✅ 플랜 리뷰 또는 코드 리뷰에서 이미지 첨부하기
✅ 펜 도구로 자유롭게 그리기
✅ 화살표 도구로 중요 영역 표시하기
✅ 원형 도구로 영역 선택하기
✅ 주석 색상과 선 굵기 조정하기
✅ 단축키로 빠르게 도구 전환 및 조작하기

현재 겪고 있는 문제

문제 1: UI 디자인 시안이나 플로우차트를 리뷰할 때, 텍스트 설명만으로는 직관적이지 않아 문제 영역을 표시해야 합니다.

문제 2: 코드 리뷰에 스크린샷 주석을 추가하고 싶지만, "여기에 문제가 있습니다"라고 텍스트로만 설명할 수 있고 이미지에 직접 표시할 수 없습니다.

문제 3: 팀에서 공유한 이미지 링크를 받았을 때, 빠르게 피드백을 표시하고 싶지만 로컬에 다운로드해서 다른 도구로 처리하고 싶지 않습니다.

Plannotator가 도와드립니다:

브라우저에서 직접 이미지에 마크업, 로컬 다운로드 불필요
펜, 화살표, 원형 세 가지 도구로 모든 마크업 시나리오 커버
5가지 색상과 5가지 선 굵기로 유연한 마크업 효과
단축키 조작으로 마크업 효율성 향상

언제 이 기능을 사용하나요

사용 시나리오:

UI 디자인 시안, 플로우차트, 아키텍처 다이어그램 리뷰 시 문제 표시가 필요할 때
코드 리뷰에서 스크린샷을 찍고 코드 문제를 표시해야 할 때
마크업된 이미지를 팀원에게 공유할 때
이미지에서 중요 영역을 선택하거나 화살표로 안내가 필요할 때

🎒 시작하기 전 준비

사전 조건

이 튜토리얼은 다음을 완료했다고 가정합니다:

✅ 플랜 리뷰 기초 또는 코드 리뷰 기초 완료
✅ 플랜 리뷰 또는 코드 리뷰 페이지를 여는 방법 숙지
✅ 기본적인 주석 조작 이해

핵심 개념

이미지 주석의 세 가지 도구:

도구	아이콘	단축키	용도
펜	🖊️	1	자유 그리기, 손글씨 주석이나 임의 형태 선택에 적합
화살표	➡️	2	중요 영역 표시 또는 방향 지시, 포인트 투 포인트 마크업에 적합
원형	⭕	3	영역 선택, 특정 요소 강조에 적합

워크플로우:

이미지 업로드 → 도구 선택 → 색상과 크기 조정 → 이미지에 그리기 → 저장

따라하기

1단계: 플랜 리뷰 또는 코드 리뷰 페이지 열기

왜 필요한가요 Plannotator의 이미지 주석 기능은 플랜 리뷰와 코드 리뷰에 통합되어 있습니다.

조작 방법

플랜 리뷰 시작 (Claude Code 트리거 또는 OpenCode에서 submit_plan 호출)
또는 /plannotator-review 명령어를 실행하여 코드 리뷰 시작

확인 사항:

브라우저에서 리뷰 페이지가 열림
우측 상단에 「Upload」 또는 「첨부」 버튼이 있음

2단계: 이미지 업로드

왜 필요한가요 마크업을 하려면 먼저 이미지를 업로드해야 합니다.

조작 방법

페이지 우측 상단의 「Upload」 또는 「첨부」 버튼 클릭
마크업할 이미지 선택 (PNG, JPEG, WebP 형식 지원)
이미지 업로드 후 주석 목록에 표시됨

확인 사항:

이미지 썸네일이 주석 영역에 나타남
썸네일을 클릭하면 마크업 에디터가 열림

이미지 소스

다음 방법으로 이미지를 가져올 수 있습니다:

스크린샷 후 붙여넣기 (Ctrl+V / Cmd+V)
로컬 파일에서 선택
이미지를 페이지로 드래그 앤 드롭

3단계: 이미지 주석 에디터 열기

왜 필요한가요 마크업 에디터는 그리기 도구와 색상 선택 기능을 제공합니다.

조작 방법

업로드된 이미지 썸네일 클릭
이미지 주석 에디터가 팝업으로 열림

확인 사항:

이미지가 중앙에 표시됨
상단에 도구 모음이 있음
도구 모음 왼쪽부터: 도구 선택, 선 굵기, 색상 선택, 실행 취소, 전체 지우기, 저장

4단계: 펜 도구로 자유롭게 그리기

왜 필요한가요 펜 도구는 손글씨 주석이나 임의 형태 선택에 적합합니다.

조작 방법

펜 도구가 선택되어 있는지 확인 (🖊️ 아이콘, 기본 선택됨)
마우스 왼쪽 버튼을 누른 채로 이미지 위에 그리기
마우스를 놓으면 그리기 완료

확인 사항:

마우스 이동 시 따라오는 선 궤적
마우스를 놓으면 그린 형태가 이미지에 고정됨

펜 특징

perfect-freehand 라이브러리를 사용하여 부드러운 손그림 효과 구현
압력 감지 지원 (기기가 지원하는 경우)
선이 굵을수록 더 부드러운 선

5단계: 화살표 도구로 중요 포인트 표시

왜 필요한가요 화살표는 포인트 투 포인트 마크업에 적합하며, 문제 위치를 명확하게 지시합니다.

조작 방법

화살표 도구 클릭 (➡️ 아이콘) 또는 단축키 2 누르기
이미지에서 화살표 시작점 클릭
목표 위치로 드래그한 후 마우스를 놓아 화살표 그리기 완료

확인 사항:

시작점에서 끝점까지의 직선
끝점에 화살표 머리가 있어 목표 위치를 가리킴

화살표 그리기 팁

시작점은 화살표 꼬리, 끝점은 화살표 머리
드래그하는 동안 화살표 방향을 실시간으로 미리 볼 수 있음
"여기에 문제가 있습니다" 또는 "여기를 수정해야 합니다" 등의 시나리오에 적합

6단계: 원형 도구로 영역 선택

왜 필요한가요 원형은 특정 요소를 강조하는 데 적합하며, 선택 범위가 명확합니다.

조작 방법

원형 도구 클릭 (⭕ 아이콘) 또는 단축키 3 누르기
이미지에서 원의 한쪽 가장자리 클릭
반대쪽 가장자리로 드래그한 후 마우스를 놓아 원형 그리기 완료

확인 사항:

시작점에서 끝점까지의 연결선이 지름인 원형
원의 중심은 두 점 연결선의 중점

원형 그리기 원리

원형 도구는 가장자리에서 가장자리로 그립니다:

첫 번째 클릭: 원의 한쪽 가장자리
드래그: 원의 지름 결정
놓기: 원 그리기 완료

소스 코드 구현 (utils.ts:95-124):

typescript

// 중심은 시작점과 끝점의 중점
const cx = (x1 + x2) / 2;
const cy = (y1 + y2) / 2;

// 반지름은 두 점 거리의 절반
const radius = Math.hypot(x2 - x1, y2 - y1) / 2;

7단계: 주석 색상 조정

왜 필요한가요 다른 색상으로 다른 유형의 주석을 구분할 수 있습니다 (예: 빨간색은 오류, 녹색은 제안).

조작 방법

도구 모음에서 색상 원 클릭
선택 가능한 색상: 빨간색, 노란색, 녹색, 파란색, 흰색

확인 사항:

현재 선택된 색상 원이 확대되어 표시됨
새로 그리는 모든 주석이 현재 색상을 사용함

색상 사용 권장 사항

빨간색: 오류, 문제, 삭제해야 할 내용
노란색: 경고, 주의, 확인이 필요한 부분
녹색: 제안, 최적화, 개선 의견
파란색: 추가 설명, 메모
흰색: 어두운 배경 이미지에 적합

8단계: 선 굵기 조정

왜 필요한가요 다른 크기의 선 굵기는 다른 마크업 시나리오에 적합합니다.

조작 방법

도구 모음에서 - 또는 + 버튼 클릭
또는 현재 선 굵기 미리보기 확인 (원형 점)

확인 사항:

선택 가능한 선 굵기: 3, 6, 10, 16, 24
도구 모음 중앙에 현재 선 굵기의 미리보기 원이 표시됨

선 굵기 권장 사항

3: 작은 요소 정밀 마크업 (버튼, 아이콘 등)
6: 일반 마크업 (기본값)
10: 굵은 선 마크업, 큰 영역 선택에 적합
16: 매우 굵은 마크업, 중요 포인트 강조에 적합
24: 최대 선 굵기, 매우 큰 영역 강조에 적합

9단계: 실행 취소와 전체 지우기

왜 필요한가요 마크업 과정에서 실수는 피할 수 없으며, 실행 취소하거나 다시 시작해야 합니다.

조작 방법

이전 단계 실행 취소: 실행 취소 아이콘 (↩️) 클릭 또는 Cmd+Z / Ctrl+Z 누르기
모든 주석 지우기: 지우기 아이콘 (❌) 클릭

확인 사항:

실행 취소: 마지막으로 그린 주석이 사라짐
전체 지우기: 모든 주석이 제거되고 원본 이미지로 복원됨

전체 지우기 주의

전체 지우기 작업은 실행 취소할 수 없으니 신중하게 사용하세요. 먼저 실행 취소로 단계별로 되돌리는 것을 권장합니다.

10단계: 주석 저장

왜 필요한가요 주석을 저장하면 이미지가 주석에 병합되어 리뷰에서 볼 수 있습니다.

조작 방법

도구 모음 오른쪽의 저장 아이콘 (✅) 클릭
또는 Esc 또는 Enter 키 누르기
또는 팝업 외부 영역 클릭

확인 사항:

팝업이 닫힘
이미지 썸네일이 마크업된 버전으로 업데이트됨
이미지가 현재 주석에 첨부됨

저장 메커니즘

주석을 그리지 않은 경우, 원본 이미지가 그대로 저장됨
주석이 있는 경우, 원본 이미지와 주석이 하나의 새 이미지로 병합됨
병합된 이미지는 PNG 형식으로 저장되어 고품질 유지

체크포인트 ✅

학습 성과 확인:

[ ] 리뷰 페이지에 이미지를 성공적으로 업로드할 수 있음
[ ] 펜, 화살표, 원형 세 가지 도구로 주석을 그릴 수 있음
[ ] 주석 색상과 선 굵기를 조정할 수 있음
[ ] 단축키 (1/2/3, Cmd+Z, Esc)로 빠르게 조작할 수 있음
[ ] 잘못된 주석을 실행 취소할 수 있음
[ ] 주석이 추가된 이미지를 저장할 수 있음

문제 해결

문제 1: 화살표 방향이 반대로 됨

현상: 화살표가 잘못된 방향을 가리킴.

원인: 화살표 도구는 시작점(꼬리)에서 끝점(머리)으로 그립니다.

해결 방법:

다시 그리기, 시작점이 화살표 꼬리이고 끝점이 화살표 머리인지 확인
이미 그린 경우, 실행 취소 후 다시 그리기

문제 2: 원형 위치가 맞지 않음

현상: 원형이 대상 영역을 선택하지 못함.

원인: 원형 도구는 가장자리에서 가장자리로 그리며, 중심은 두 점의 중점입니다.

해결 방법:

첫 번째 클릭을 대상 영역의 가장자리에서
반대쪽 가장자리로 드래그하여 대상 영역이 원 안에 있도록 함
조정 시 실행 취소 후 다시 그리기 가능

문제 3: 선이 너무 굵거나 가늘음

현상: 마크업 효과가 이상적이지 않음.

원인: 선 굵기가 현재 시나리오에 적합하지 않음.

해결 방법:

도구 모음의 - 또는 + 버튼으로 선 굵기 조정
작은 요소는 3-6, 큰 영역은 10-24 사용

문제 4: 색상이 보이지 않음

현상: 어두운 배경에서 검은색 선을 사용하면 주석이 보이지 않음.

원인: 색상 선택이 부적절함.

해결 방법:

어두운 배경에는 흰색 또는 노란색 사용
밝은 배경에는 빨간색, 녹색 또는 파란색 사용

단축키 빠른 참조

단축키	기능
`1`	펜 도구로 전환
`2`	화살표 도구로 전환
`3`	원형 도구로 전환
`Cmd+Z` / `Ctrl+Z`	이전 단계 실행 취소
`Esc` / `Enter`	주석 저장

이번 강의 요약

이번 강의에서 배운 내용:

이미지 업로드: 업로드 버튼 또는 붙여넣기로 리뷰 페이지에 추가
세 가지 마크업 도구:
- 펜 (1): 자유 그리기, 손글씨 주석에 적합
- 화살표 (2): 포인트 투 포인트 마크업, 중요 포인트 지시에 적합
- 원형 (3): 영역 선택, 강조 표시에 적합
마크업 스타일 조정: 5가지 색상, 5가지 선 굵기
실행 취소와 전체 지우기: 잘못된 주석 수정
주석 저장: 주석을 이미지에 병합

다음 강의 예고

다음 강의에서는 **코드 리뷰 기초**를 배웁니다.
배우게 될 내용:
/plannotator-review 명령어로 git diff 리뷰하는 방법
side-by-side와 unified 뷰 간 전환
줄 번호 클릭으로 코드 범위 선택
줄 단위 주석 추가 (comment/suggestion/concern)
다른 diff 유형으로 전환
AI Agent에게 피드백 전송

부록: 소스 코드 참조

소스 코드 위치 보기

업데이트 날짜: 2026-01-24

기능	파일 경로	줄 번호
도구 타입 정의	`packages/ui/components/ImageAnnotator/types.ts`	1-40
렌더링 함수	`packages/ui/components/ImageAnnotator/utils.ts`	1-148
메인 컴포넌트	`packages/ui/components/ImageAnnotator/index.tsx`	1-233
도구 모음 컴포넌트	`packages/ui/components/ImageAnnotator/Toolbar.tsx`	1-219
Annotation 인터페이스	`packages/ui/types.ts`	11-33

핵심 타입:

Tool (도구 타입):

typescript

export type Tool = 'pen' | 'arrow' | 'circle';

Point (좌표점):

typescript

export interface Point {
  x: number;
  y: number;
  pressure?: number;
}

Stroke (선):

typescript

export interface Stroke {
  id: string;
  tool: Tool;
  points: Point[];
  color: string;
  size: number;
}

AnnotatorState (주석기 상태):

typescript

export interface AnnotatorState {
  tool: Tool;
  color: string;
  strokeSize: number;
  strokes: Stroke[];
  currentStroke: Stroke | null;
}

COLORS (색상 배열):

typescript

export const COLORS = [
  '#ef4444', // red
  '#eab308', // yellow
  '#22c55e', // green
  '#3b82f6', // blue
  '#ffffff', // white
] as const;

STROKE_SIZES (선 굵기):

typescript

const STROKE_SIZES = [3, 6, 10, 16, 24];

핵심 함수:

renderPenStroke() (펜 선 렌더링):

perfect-freehand 라이브러리를 사용하여 부드러운 손그림 효과 구현
압력 감지 지원 (pressure 필드)

renderArrow() (화살표 렌더링):

시작점에서 끝점까지 직선 그리기
끝점에 화살표 머리 그리기

renderCircle() (원형 렌더링):

두 점의 중점을 원의 중심으로 계산
두 점 거리의 절반을 반지름으로 계산

renderStroke() (도구 타입에 따른 렌더링):

tool 필드에 따라 해당 렌더링 함수 호출
스케일링 지원 (scale 매개변수)

Annotation.imagePaths (첨부 이미지 필드):

typescript

export interface Annotation {
  // ...
  imagePaths?: string[]; // Attached images (local paths or URLs)
}

단축키 처리 (index.tsx:33-59):

typescript

// 1/2/3 to switch tools
if (e.key === '1') setState(s => ({ ...s, tool: 'pen' }));
if (e.key === '2') setState(s => ({ ...s, tool: 'arrow' }));
if (e.key === '3') setState(s => ({ ...s, tool: 'circle' }));

// Cmd+Z to undo
if ((e.metaKey || e.ctrlKey) && e.key === 'z') {
  e.preventDefault();
  handleUndo();
}

이미지 주석 추가: 펜, 화살표, 원형으로 이미지 마크업하기 ​

이 강의에서 배우는 것 ​

현재 겪고 있는 문제 ​

언제 이 기능을 사용하나요 ​

🎒 시작하기 전 준비 ​

핵심 개념 ​

따라하기 ​

1단계: 플랜 리뷰 또는 코드 리뷰 페이지 열기 ​

2단계: 이미지 업로드 ​

3단계: 이미지 주석 에디터 열기 ​

4단계: 펜 도구로 자유롭게 그리기 ​

5단계: 화살표 도구로 중요 포인트 표시 ​

6단계: 원형 도구로 영역 선택 ​

7단계: 주석 색상 조정 ​

8단계: 선 굵기 조정 ​

9단계: 실행 취소와 전체 지우기 ​

10단계: 주석 저장 ​

체크포인트 ✅ ​

문제 해결 ​

문제 1: 화살표 방향이 반대로 됨 ​

문제 2: 원형 위치가 맞지 않음 ​

문제 3: 선이 너무 굵거나 가늘음 ​

문제 4: 색상이 보이지 않음 ​

단축키 빠른 참조 ​

이번 강의 요약 ​

다음 강의 예고 ​

부록: 소스 코드 참조 ​

이미지 주석 추가: 펜, 화살표, 원형으로 이미지 마크업하기

이 강의에서 배우는 것

현재 겪고 있는 문제

언제 이 기능을 사용하나요

🎒 시작하기 전 준비

핵심 개념

따라하기

1단계: 플랜 리뷰 또는 코드 리뷰 페이지 열기

2단계: 이미지 업로드

3단계: 이미지 주석 에디터 열기

4단계: 펜 도구로 자유롭게 그리기

5단계: 화살표 도구로 중요 포인트 표시

6단계: 원형 도구로 영역 선택

7단계: 주석 색상 조정

8단계: 선 굵기 조정

9단계: 실행 취소와 전체 지우기

10단계: 주석 저장

체크포인트 ✅

문제 해결

문제 1: 화살표 방향이 반대로 됨

문제 2: 원형 위치가 맞지 않음

문제 3: 선이 너무 굵거나 가늘음

문제 4: 색상이 보이지 않음

단축키 빠른 참조

이번 강의 요약

다음 강의 예고

부록: 소스 코드 참조