Pixel Layer Image Editor

VS Code에서 이미지 변환, 매직완드 선택, 복사·붙여넣기, 레이어와 크기 변경에 집중하는 픽셀·레이어 이미지 에디터입니다. Simple Image Editor에서 영감을 받아 독립적으로 구현했습니다.

문서 언어

This document is written in Korean. For instructions in English, see the English README.

• 한국어 — 현재 문서
• 영어 — 영문 사용 및 설치 안내

일반 VS Code에 설치하기 (VSIX)

F5 개발 창 없이 사용하려면 확장을 VSIX 파일로 패키징한 뒤 설치합니다. 개인 사용에는 Visual Studio Marketplace 공개나 게시자 계정 인증이 필요하지 않습니다. 패키징에는 Node.js와 npm, 최초 npx 실행에는 인터넷 연결이 필요합니다.

프로젝트 폴더에서 실행합니다.

cd ~/ws/vscode-image-editor
npx @vscode/vsce package
code --install-extension ./vscode-image-editor-0.4.0.vsix

생성되는 파일 이름의 버전은 package.json의 version을 따릅니다. 위 예시는 현재 버전 0.4.0 기준입니다.

code 명령을 사용할 수 없다면 VS Code의 확장 패널에서 **… → Install from VSIX…**를 선택하고 생성된 파일을 지정합니다.

설치 후 일반 VS Code 창에서 다음과 같이 설정합니다.

1. 명령 팔레트에서 Developer: Reload Window를 실행합니다.
2. 탐색기의 이미지 파일을 우클릭하고 **Open With…**를 선택합니다.
3. Configure default editor… → Pixel Layer Image Editor — Preview를 선택합니다. PNG·JPEG·WebP 등 사용할 확장자별로 설정합니다.
4. 이후 이미지는 미리보기로 열리고, 상단 Edit을 누르면 편집할 수 있습니다.

수정한 버전으로 업데이트

소스 수정은 설치된 확장에 자동 반영되지 않습니다. 프로젝트 폴더에서 다시 패키징하고 설치합니다. 같은 버전을 교체할 때는 --force를 사용합니다.

npx @vscode/vsce package
code --install-extension ./vscode-image-editor-0.4.0.vsix --force

버전을 변경했다면 실제 생성된 VSIX 파일 이름으로 설치합니다. 설치 후 Developer: Reload Window를 실행합니다.

탐색기에서 이미지 열기

PNG·JPEG·WebP 파일을 우클릭한 뒤 Open With… → Pixel Layer Image Editor — Preview를 선택할 수 있습니다. 탐색기에서 파일을 클릭할 때마다 이 미리보기를 사용하려면 **Open With… → Configure default editor…**에서 해당 항목을 지정합니다. 기존 이미지 확장의 기본 연결 설정은 유지됩니다. 이미지 미리보기는 원본 파일 탭에서 열리고, 편집 모드는 별도의 레이어 프로젝트를 생성합니다.

미리보기와 편집 모드

이미지는 기본적으로 미리보기(Preview) 모드로 열립니다. 확대·축소와 내보내기가 가능하며 선택·삭제·붙여넣기 등 편집은 비활성화됩니다. 상단 Edit을 누르면 메뉴, 왼쪽 도구 막대, 오른쪽 속성(Properties)·히스토리(History)·레이어(Layers) 패널이 표시됩니다. 미리보기로 돌아가도 편집 내용은 유지됩니다. 모든 화면 요소와 명령 이름은 영어로 표시합니다.

작업 화면과 패널

오른쪽 Canvas & Image Size, Layers, History 패널은 헤더의 접기 버튼으로 접고 펼칠 수 있으며 마지막 상태가 저장됩니다. Ruler를 켜면 캔버스 상단과 왼쪽 바깥쪽에 눈금자가 표시되고, 캔버스 스크롤·확대 시에도 작업 영역에 고정됩니다. 눈금자를 클릭하면 가이드라인이 추가되며, 상단 눈금자는 세로 가이드, 왼쪽 눈금자는 가로 가이드를 만듭니다. 가이드라인은 드래그할 수 있고 방향별 최대 10개까지 추가할 수 있습니다. 픽셀 격자와 눈금자는 화면 표시 전용입니다.

레이어 패널의 이미지 아이콘은 Add Empty Layer입니다. 새 빈 투명 레이어를 추가하며 이미지 파일을 여는 기능이 아닙니다. 이미지를 별도 레이어로 추가하려면 외부 이미지를 Ctrl/Cmd+V로 붙여넣습니다.

확대·축소

미리보기와 편집 모드 모두에서 하단 − / +, 배율 입력(1–3200%), 프리셋, Fit, 1:1을 사용할 수 있습니다. 왼쪽 Zoom (Z) 도구를 선택해 캔버스를 클릭하면 확대되고, Ctrl/Cmd를 누른 채 클릭하면 축소됩니다. Zoom 도구 선택 중 마우스 휠도 확대·축소에 사용할 수 있으며, 일반 도구에서는 Ctrl/Cmd + 휠로 동작합니다. 키보드 + / −, 0(Fit), 1(100%)도 지원합니다. 확대 시 스크롤로 이미지의 다른 영역을 볼 수 있습니다.

픽셀 격자

도트 작업은 기본으로 켜져 있는 캔버스 아래 Pixel Grid 옵션으로 실제 이미지 픽셀 경계를 확인할 수 있습니다. 300% 이상에서만 표시되며 배율에 맞춰 격자 간격이 조정됩니다. 300% 미만으로 축소하면 자동으로 숨겨지고 다시 확대하면 표시됩니다. 미리보기와 편집 모드 모두 지원하며, 그리드는 화면 표시 전용으로 저장·내보내기 이미지와 히스토리에 포함되지 않습니다.

편집

• 매직완드: 활성 레이어에서 클릭한 픽셀과 유사한 색을 선택합니다. 허용 오차는 0~255이며, 인접 영역을 끄면 레이어 전체에서 같은 색을 선택합니다. 파란 오버레이가 선택 영역입니다.
• 선택: 반전·해제·삭제를 지원합니다. 선택이 없는 복사·삭제는 활성 레이어 전체에 적용됩니다.
• 복사·붙여넣기: 선택 영역을 복사해 새 레이어에 붙여넣습니다. 에디터 내부 클립보드를 기본으로 사용하며, 시스템 클립보드 쓰기가 허용되는 환경에서는 PNG도 복사합니다. 외부 이미지는 Ctrl/Cmd+V로 가져옵니다.
• 레이어: 이미지 추가, 이름 변경, 표시·숨김, 불투명도, 순서 변경, 삭제를 지원합니다. 레이어 이동 도구에서 드래그한 뒤 놓으면 위치가 적용됩니다.
• 캔버스 크기: 픽셀 배율을 유지하고 기준점에 따라 작업 영역을 변경합니다. 축소하면 영역 밖 픽셀은 잘립니다. 실행 취소로 복원할 수 있습니다.
• 이미지 크기: 모든 레이어를 함께 리샘플링합니다. 비율 유지 옵션을 지원합니다.
• 히스토리: VS Code 문서의 실행 취소·다시 실행과 연결됩니다. 작업 목록의 항목을 누르면 히스토리 항목을 추가하지 않고 해당 상태로 이동합니다. 편집기의 실행 취소·다시 실행도 같은 목록에서 이동합니다. 이전 상태에서 새로 편집하면 이후 기록은 교체됩니다. 목록은 현재 편집 세션에서 최대 30개, 약 48MB로 제한하며 프로젝트에는 저장하지 않습니다.

사각형 선택

왼쪽 Select (M) 또는 도구 목록의 Rectangular Select를 선택하고 클릭·드래그합니다. 파란 오버레이가 선택된 픽셀입니다. 아래 수정 키는 드래그를 시작할 때 누릅니다.

선택은 연필 그리기·복사·잘라내기·삭제에 적용되며 선택 변경 자체는 히스토리에 추가되지 않습니다. 선택이 전혀 없는 상태의 복사·잘라내기·삭제는 활성 레이어 전체에 적용되므로 주의하세요.

연필 도구 · 팔레트 · 불투명도 · 디더

편집 모드의 왼쪽 툴바에서 연필 도구(Pencil, B)를 선택합니다. 툴바에는 아이콘, 영문 기능명, 도구 단축키가 표시됩니다.

디더는 이미지 좌표에 고정된 4×4 패턴이며 빈 부분은 기존 픽셀을 유지합니다. 같은 스트로크에서 같은 픽셀을 반복해서 지나가도 불투명도는 한 번만 적용됩니다. 새 스트로크를 겹치면 색이 누적됩니다. 레이어 불투명도는 이와 별도로 레이어 전체에 적용됩니다.

활성화된 표시 레이어에 그리며, 선택 영역이 있으면 그 안에서만 적용됩니다. 빈 프로젝트에는 첫 유효 스트로크 때 레이어가 생성됩니다. 드래그 한 번이 히스토리 한 단계이며 드래그 중 Escape로 취소할 수 있습니다.

도트 편집 예시

1. 편집 모드를 켜고 사각 선택 도구(Select, M)로 편집할 영역을 지정합니다.
2. 연필 도구(B)를 선택하고 크기 1px, 팔레트 색상, 불투명도 100%, 디더 0%를 설정합니다.
3. 300% 이상 확대하고 픽셀 격자(Pixel Grid)를 켠 뒤 그립니다.
4. 체크 무늬 음영은 디더 50%로 그립니다. 잘못 그린 스트로크는 실행 취소(Undo)로 취소합니다.
5. 저장(Save)으로 레이어 프로젝트를 저장하거나 내보내기(Export)로 이미지를 내보냅니다.

저장과 내보내기

프로젝트 저장 / Ctrl·Cmd+S는 레이어를 포함하는 .mimage 파일을 저장합니다. VS Code의 수정 표시, 닫기 시 저장 확인, 문서 복구 기능을 사용합니다.

내보내기는 보이는 레이어를 합쳐 PNG·JPEG·WebP로 저장합니다. JPEG의 투명 영역은 흰색으로 처리합니다. JPEG·WebP 품질은 첫 버전에서 92%로 고정합니다. 원본 이미지는 프로젝트와 별도로 유지됩니다.

화면 내 도움말

미리보기와 편집 모드 모두에서 상단 Help 또는 ? 키로 영어 도움말을 열 수 있습니다. 검색창에서 도구, 단축키, 픽셀 격자, 저장·내보내기, 문제 해결 항목을 검색할 수 있습니다. Escape 또는 닫기 버튼으로 돌아옵니다. 도움말이 열린 동안 편집 단축키와 붙여넣기는 캔버스에 적용되지 않습니다.

단축키

개발 모드로 실행

1. 이 폴더를 VS Code로 엽니다.
2. F5 → Run Pixel Layer Image Editor로 확장 개발 호스트를 실행합니다. 별도 빌드나 런타임 패키지 설치는 필요 없습니다.
3. 새 창의 명령 팔레트에서 Pixel Layer Image Editor: Open Image를 실행하고 PNG·JPEG·WebP 이미지를 선택합니다. 탐색기 이미지 파일의 우클릭 메뉴에서도 실행할 수 있습니다.
4. 원본 이미지의 미리보기 탭이 바로 열립니다. 편집 버튼(Edit)을 누르면 저장되지 않은 편집 프로젝트로 전환되며, 처음 저장할 때 .mimage 위치를 선택합니다.
5. 빈 작업은 Pixel Layer Image Editor: New Project로 시작합니다.

F5 키(실행 및 디버그 단축키)로 개발 실행

저장소를 이동했다면 code ~/ws/vscode-image-editor로 새 경로의 폴더를 엽니다. 실행 및 디버그 패널에서 Run Pixel Layer Image Editor를 선택한 뒤 키보드의 **F5 키(실행 및 디버그 단축키)**를 누릅니다. 기본 F5 설정은 디버거 연결을 기다리지 않고 개발 확장을 실행합니다 (noDebug: true). 중단점이 필요하면 Run Pixel Layer Image Editor + Webview Debugging을 선택합니다. 현재 환경에서 확장 호스트 디버거의 localhost 연결 오류가 재현되어, 이 선택 설정은 정상 동작이 보장되지 않습니다.

웹뷰 디버깅 연결은 IPv4 주소 127.0.0.1을 사용하지만, VS Code 내장 디버거의 확장 호스트 연결은 별도입니다. 디버거 없이 개발 확장을 여는 방법은 다음과 같습니다.

code --new-window --extensionDevelopmentPath="$HOME/ws/vscode-image-editor"

새 창이 열리면 명령 팔레트에서 Pixel Layer Image Editor: Open Image 또는 Pixel Layer Image Editor: New Project를 실행합니다. F5 자체는 이미지 편집 화면을 자동으로 열지 않습니다.

개발과 검증

• npm run check: JavaScript 문법 검사
• npm test: 매직완드 연결 영역·허용 오차·투명도·행 경계·프로젝트 검증 테스트
• node test/editor.smoke.cjs: Playwright가 설치된 환경에서 브라우저 통합 검사. 브라우저 경로는 CHROME_PATH로 지정할 수 있습니다.

브라우저 검사는 VS Code 메시지 처리를 모의합니다. 실제 확장 개발 호스트에서 이미지 열기, 저장 확인, 문서 복구 및 OS별 클립보드 권한은 별도 확인이 필요합니다.

첫 버전은 최대 64개 레이어, 한 변 8192px, 총 16,777,216픽셀까지 허용합니다. 각 레이어는 캔버스 전체 크기로 유지하므로 큰 이미지와 많은 레이어는 메모리 사용량이 큽니다. 프로젝트는 JSON 안에 PNG 레이어를 저장합니다. 색상 프로필과 EXIF 메타데이터 보존, 애니메이션 이미지, 레이어 잠금, 소프트 브러시·텍스트·필터는 지원하지 않습니다.

구조: src/extension.js는 VS Code 문서와 파일 작업, media/editor.js는 캔버스 편집과 화면 구성, media/core.js는 선택 알고리즘과 검증을 담당합니다. VS Code 사용자 지정 편집기 API를 기반으로 구현했습니다.

Marketplace 수동 업데이트

GitHub Actions 자동 게시를 사용하지 않습니다. 새 버전을 게시할 때는 로컬에서 검사·패키징한 뒤 Marketplace 관리 페이지에 VSIX를 직접 업로드합니다.

npm install --global @vscode/vsce
npm run check
npm test
npm run package

생성된 vscode-image-editor-<version>.vsix 파일을 devchan64 게시자 관리 페이지의 기존 확장에 업로드합니다. 게시 전에 package.json의 버전을 이전 게시 버전보다 높게 변경해야 합니다.