RuiC-PoseAtlas 튜토리얼: 다국어 인체 포즈 레퍼런스 갤러리 구축 및 사용

RuiC-PoseAtlas 알아보기

RuiC-PoseAtlas는 완전한 정적 방식으로 작동하며 런타임 의존성이 전혀 없는 인체 포즈 참고 자료 라이브러리입니다. 이 프로젝트에는 288개 포즈 그룹과 1,439개의 인체 모델 선화가 수록되어 있으며, 동일한 포즈의 정면, 사선, 측면, 위쪽 및 아래쪽 시점을 한곳에서 관리합니다. 이를 통해 창작자는 신체 자세, 비율, 사지의 방향과 카메라 관계를 연속적으로 비교할 수 있습니다.

AI 드로잉, 일러스트, 만화, 3D 모델링, 애니메이션, 사진 구도와 시각 디자인에 적합하며, 네이티브 프런트엔드 프로젝트의 학습 사례로도 활용할 수 있습니다. 웹사이트는 순수 HTML, CSS 및 ES Modules로 작성되었으며 React, Vue 또는 번들러에 의존하지 않습니다.

콘텐츠 안내: 이 프로젝트는 성인 창작자를 대상으로 하며 일부 콘텐츠는 미성년자에게 적합하지 않습니다. 사용 시 거주 지역의 법률 및 플랫폼 규정을 준수하세요.

바로 둘러보려면 RuiC-PoseAtlas 온라인 데모를 열면 됩니다. 소스 코드를 살펴보거나 데이터를 사용자 지정하거나 직접 배포하려는 경우에만 다음 단계에 따라 저장소를 복제하세요.

주요 기능

• 다각도 비교: 각 포즈 그룹에는 4~5개의 각도가 포함되어 있으며 카드 또는 큰 이미지 페이지에서 전환할 수 있습니다.
• 두 가지 탐색 모드: ‘포즈별’ 모드는 같은 그룹의 각도를 묶고, ‘개별 이미지’ 모드는 각 각도를 펼쳐 표시합니다.
• 조합 필터: 시리즈, 분류 및 각도로 필터링할 수 있으며, 프로젝트에는 4개의 콘텐츠 시리즈와 26개의 하위 분류가 포함되어 있습니다.
• 다국어 검색: 중국어, 영어, 일본어 이름을 동시에 색인하며 포즈 번호, 분류 및 시리즈로도 검색할 수 있습니다.
• 3개 언어 인터페이스: 중국어, English 및 日本語를 즉시 전환할 수 있으며 선택 사항은 localStorage에 저장됩니다.
• 키보드 조작: 방향키로 각도와 포즈를 전환하고 Esc로 큰 이미지를 닫을 수 있습니다.
• 원본 이미지 다운로드: 큰 이미지 페이지에서 900 × 1200 PNG 파일을 다운로드할 수 있습니다.
• 딥 링크: URL을 통해 특정 언어, 포즈 및 각도를 직접 공유할 수 있습니다.
• 반응형 레이아웃: 데스크톱 다열 그리드, 모바일 2열 카드 및 좁은 화면의 큰 이미지 탐색을 지원합니다.
• 엔지니어링 검증: npm run verify로 데이터, 번역, 파일 참조, 이미지 크기 및 i18n 키를 검사할 수 있습니다.

실행 환경 준비

일상적인 탐색에는 최신 브라우저와 정적 HTTP 서버만 있으면 됩니다. README에서는 Python 3 사용을 권장합니다. 데이터를 다시 생성하거나 이미지를 복구하거나 전체 무결성 검사를 실행하려면 Node.js 18 이상도 필요합니다.

• Chrome, Edge, Safari 또는 Firefox와 같은 최신 브라우저
• Python 3 또는 기타 정적 서버
• 스크립트 작업에만 사용하는 Node.js 18 이상
• 충분한 디스크 공간: PNG 원본은 약 654 MB, 썸네일은 약 25 MB

로컬 설치 및 실행

1단계: 저장소 복제

git clone https://github.com/HRuiCcc/RuiC-PoseAtlas.git
cd RuiC-PoseAtlas

저장소에는 1,439개의 PNG 원본과 1,439개의 JPEG 썸네일이 모두 포함되어 있으므로 처음 복제할 때 다소 시간이 걸릴 수 있습니다.

2단계: 정적 서버 실행

python3 -m http.server 8123 --bind 127.0.0.1

그런 다음 브라우저에서 다음 주소에 접속하세요.

http://127.0.0.1:8123/

Node.js가 이미 설치되어 있다면 프로젝트에서 제공하는 명령을 직접 실행할 수도 있습니다.

npm start

index.html을 직접 더블클릭하지 마세요. 페이지는 fetch()를 통해 data/poses.json을 읽습니다. file:// 프로토콜에서는 브라우저의 동일 출처 정책에 의해 요청이 차단되어 빈 페이지가 표시될 수 있습니다.

기본 사용 방법

포즈 검색 및 필터링

1. 검색창에 중국어, 영어 또는 일본어 포즈 이름을 입력하거나 P019와 같은 번호를 입력합니다.
2. 상단의 시리즈 태그를 사용해 콘텐츠 범위를 좁힙니다.
3. 분류와 각도를 계속 선택해 여러 필터 조건을 조합합니다.
4. ‘포즈별’과 ‘개별 이미지’ 사이를 전환하여 포즈 그룹을 비교하거나 이미지를 하나씩 필터링합니다.
5. 모바일에서는 ‘필터’를 눌러 접혀 있는 필터 패널을 펼칩니다.

카드 및 큰 이미지 탐색

카드 하단의 각도 썸네일을 클릭하면 해당 각도를 카드에서 바로 미리 볼 수 있습니다. 카드의 대표 이미지나 제목을 클릭하면 큰 이미지가 열립니다. 카드에서 먼저 각도를 선택한 뒤 대표 이미지를 클릭하면 큰 이미지 페이지가 해당 각도부터 표시됩니다.

큰 이미지 페이지에서는 다음 키보드 조작을 지원합니다.

• ← 및 →: 이전 또는 다음 각도로 전환합니다.
• ↑ 및 ↓: 이전 또는 다음 포즈로 전환합니다.
• Esc: 큰 이미지를 닫습니다.
• Tab: 큰 이미지 페이지의 컨트롤 사이에서 포커스를 순환합니다.

페이지에는 포즈 이름, 번호, 시리즈, 분류, 현재 각도 및 이미지 사양도 표시됩니다. 참고 자료를 저장하려면 ‘원본 이미지 다운로드(PNG)’를 클릭하세요.

언어 전환 및 딥 링크 공유

오른쪽 상단에서 중국어, 영어 및 일본어를 전환할 수 있습니다. 언어 선택은 먼저 URL 매개변수를 읽고, 다음으로 localStorage를 읽으며, 마지막으로 브라우저 언어에 따라 기본 인터페이스를 결정합니다.

http://127.0.0.1:8123/?lang=en
http://127.0.0.1:8123/?lang=ja#pose=full_single_P019&angle=side

두 번째 예시는 일본어 인터페이스를 열고 full_single_P019의 측면 각도로 이동합니다. 온라인에 배포한 후에도 동일한 매개변수와 해시 구조를 사용해 특정 콘텐츠를 공유할 수 있습니다.

프로젝트 구조 이해

프로젝트는 데이터 중심 설계를 사용하며, data/poses.json이 라이브러리의 핵심 데이터 소스입니다. 필터, 검색, 카드 및 큰 이미지 페이지는 모두 이 데이터에서 생성됩니다.

RuiC-PoseAtlas/
├── index.html
├── assets/
│   ├── css/app.css
│   ├── js/app.js
│   └── js/i18n.js
├── data/poses.json
├── img/
├── thumbs/
├── scripts/
├── .github/workflows/
└── package.json

• assets/js/app.js: 데이터 로드, 검색 및 필터링, 페이지 렌더링, 큰 이미지 상호작용과 단축키를 담당합니다.
• assets/js/i18n.js: 세 언어의 인터페이스 문구를 한곳에 저장합니다.
• data/poses.json: 288개 포즈 그룹, 세 언어 이름 및 이미지 경로를 저장합니다.
• img/: 900 × 1200 PNG 원본을 저장합니다.
• thumbs/: 300 × 400 JPEG 썸네일을 저장합니다.
• scripts/: 데이터 구축, 이미지 복구 및 무결성 검사 스크립트를 포함합니다.

데이터 재구축 및 검증

데이터 스크립트는 서드파티 패키지에 의존하지 않습니다. 원본 데이터나 영어 이름을 수정한 후 다음 명령을 실행할 수 있습니다.

npm run data
npm run verify

npm run data는 scripts/source/의 중국어·일본어 기록과 영어 이름 표를 병합하고, 포즈 번호를 기준으로 각도를 묶은 다음 압축된 data/poses.json을 생성합니다.

npm run verify는 포즈 및 이미지 수, 세 언어 이름, 시리즈 및 분류 번역, 이미지 참조, 중복 파일, 이미지 형식 및 크기, 페이지에서 사용하는 i18n 키의 완전성을 검사합니다. 데이터를 수정한 후에는 항상 이 명령을 실행하여 이미지 누락, 끊어진 링크 또는 번역 누락을 방지하세요.

새 포즈 그룹 추가

1. PNG 원본 4~5개를 img/에 넣습니다.
2. 해당하는 300 × 400 JPEG 썸네일을 thumbs/에 넣습니다.
3. scripts/source/의 원본 기록에 포즈 항목을 추가합니다.
4. scripts/en-pose-names.json에 영어 이름을 추가합니다.
5. npm run data && npm run verify를 실행합니다.

이미지를 추가하기 전에 해당 이미지의 사용 및 배포 권한을 보유하고 있는지 반드시 확인하세요. 프로젝트 소스 코드는 MIT License를 따르지만 이미지, 원본 데이터 및 이름은 MIT 라이선스의 적용 범위에 포함되지 않습니다.

누락된 이미지 파일 복구

새로 복제한 후 일부 이미지가 누락된 것을 발견하면 다음 명령을 실행할 수 있습니다.

npm run fetch-images

스크립트는 포즈 데이터에서 이미지 경로를 수집하고, 누락된 파일을 병렬로 다운로드하며, 서명이 올바른 기존 파일은 건너뛰고 PNG 및 JPEG 파일 서명을 검증합니다. 다운로드에 실패하면 다른 소스로 전환하여 다시 시도합니다. 저장소에는 Fetch image assets라는 GitHub Actions 워크플로도 제공됩니다.

정적 웹사이트로 배포

GitHub Pages 사용

저장소에는 .github/workflows/deploy-pages.yml이 포함되어 있습니다. 사이트와 관련된 파일을 main 브랜치에 푸시하면 워크플로가 자동으로 배포합니다. Actions 페이지에서 Deploy to GitHub Pages를 수동으로 실행할 수도 있습니다.

이 과정에서는 사이트 실행에 필요한 진입점, 리소스, 데이터 및 이미지만 패키징하며 README, 빌드 스크립트 및 문서 디렉터리의 기타 파일 전체를 공개하지 않습니다.

Cloudflare Pages 사용

1. Cloudflare Pages에서 GitHub 저장소를 연결합니다.
2. Framework preset을 None으로 설정합니다.
3. Build command를 비워 둡니다.
4. Output directory를 /로 설정합니다.
5. 설정을 저장하고 배포를 시작합니다.

프로젝트에서 제공하는 _headers는 원본 이미지와 썸네일에 1년의 강력한 캐시를 설정하고, 데이터 파일에는 5분 캐시를 설정하며, index.html은 매번 다시 검증하도록 구성되어 있습니다.

기타 호스팅 플랫폼

Netlify, Vercel, 오브젝트 스토리지 또는 Nginx에서도 이 프로젝트를 호스팅할 수 있습니다. 빌드 단계가 없으므로 저장소 루트 디렉터리를 정적 사이트 디렉터리로 지정하면 됩니다. 사용자 지정 도메인을 사용하는 경우 소셜 플랫폼이 커버 이미지를 가져올 수 있도록 index.html의 og:image를 절대 URL로 수정하는 것이 좋습니다.

고급 사용 팁

• 배포 용량 줄이기: 그리드 탐색만 필요하다면 썸네일만 유지하고 데이터의 원본 이미지 필드와 다운로드 로직을 조정할 수 있지만, 큰 이미지 및 원본 이미지 다운로드 기능은 사용할 수 없게 됩니다.
• 지연 로딩 활용: 이미지 갤러리 그리드는 JPEG 썸네일만 요청하고 PNG 원본은 큰 이미지를 열거나 다운로드할 때만 로드하므로, 첫 화면 표시 속도를 위해 원본 이미지를 삭제할 필요가 없습니다.
• 새 언어 추가: assets/js/i18n.js, 포즈 데이터의 names 필드와 언어 전환기를 함께 수정한 후 무결성 검사를 실행해야 합니다.
• 상대 경로 유지: 프로젝트 리소스는 모두 상대 경로를 사용하므로 도메인 루트나 하위 디렉터리에 배포할 수 있습니다.
• 수정 후 먼저 검증: 이미지를 추가하거나 분류를 조정하거나 번역을 수정하는 경우 모두 npm run verify를 실행해야 합니다.
• 배포 범위 주의: GitHub Pages의 브랜치 배포 방식을 사용하는 경우 배포 디렉터리를 제한하여 스크립트, 문서 또는 관련 없는 저장소 파일이 정적 리소스로 노출되지 않도록 해야 합니다.

저작권 및 사용 범위

프로젝트의 프런트엔드 코드, 스타일, 스크립트와 문서는 MIT License를 따르며, 이미지, 원본 데이터 및 이름의 저작권은 원저작자에게 있고 MIT 라이선스의 적용 범위에 포함되지 않습니다. 원저작자는 작품을 창작 참고 자료로 사용하는 것을 허용하며, 상업적 창작, 편집 및 참고 용도를 포함하지만 이미지 데이터 자체의 재배포, 전재 또는 재판매는 금지합니다. 상업적으로 사용하기 전에 원본 사이트의 안내를 읽고 직접 규정 준수 여부를 확인해야 합니다.

원본 프로젝트는 POSE-DB-01이며, 원저작자는 ギア입니다. RuiC-PoseAtlas는 비공식 정리 버전으로, 주로 데이터 정리, 영어 이름 보완 및 프런트엔드 재작성을 진행했습니다.

요약

RuiC-PoseAtlas는 흩어진 다각도 포즈 자료를 검색, 필터링 및 다운로드할 수 있는 3개 언어 정적 이미지 갤러리로 정리했습니다. 일반 사용자는 구도와 스타일링을 보조하는 데 바로 활용할 수 있고, 개발자는 데이터 중심 아키텍처, 네이티브 ES Modules, 국제화, 접근성 및 정적 배포 방식에서 배울 수 있습니다. 로컬 실행을 완료한 후에는 먼저 키보드 탐색과 딥 링크에 익숙해지고, 필요에 따라 데이터를 확장하거나 자체 버전을 배포하는 것을 권장합니다.