Community이미지github.com

photo-depth

단일 사진, 그림 또는 AI 생성 이미지에 웹에서 실제 깊이를 부여합니다. MoGe-2(MIT 라이선스)로 깊이 맵을 추정한 후, three.js 씬에서 사진이 창문처럼 동작하게 하거나(카메라 이동 시 가장자리 찢김 없이 유지되는 시차 효과), 사진 속 평면이나 지점의 3D 위치를 찾아 벽면 광고판, 바닥, 픽셀 아래 3D 점 등을 배치할 수 있습니다.

photo-depth란 무엇인가요?

이 스킬은 단일 2D 이미지(사진, 그림, AI 생성 이미지)를 기반으로 깊이 맵을 추정하고, 이를 three.js 3D 씬에서 활용할 수 있도록 변환합니다. 사용자는 추정된 깊이 정보를 이용해 이미지를 마치 창문처럼 동작하게 하여 카메라 이동에 따라 시차 효과를 만들거나(가장자리 찢김 없음), 이미지 내 특정 평면(벽, 표지판 등)이나 픽셀의 3D 좌표를 계산하여 객체를 배치할 수 있습니다. MoGe-2 모델(MIT 라이선스)을 사용하며, Python 환경 설정과 모델 가중치 다운로드가 필요합니다. 주로 Claude Code와 같은 터미널 기반 AI 코딩 에이전트와 함께 사용되며, 설치 스크립트와 깊이 추정, 평면 피팅 스크립트가 제공됩니다. 이 스킬은 배경, 포털, 스카이박스, 매트 페인팅 등에 깊이감을 더하거나, 이미지 속에 3D 객체를 자연스럽게 배치해야 할 때 유용합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/skyeyesec333/photo-depth/tree/main/skills/photo-depth

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

사진 깊이: 실제 공간처럼 동작하는 사진

0. 설정     MoGe-2가 포함된 Python 환경 (최초 1회, 다운로드 전 확인)        scripts/setup.sh
1. 깊이     사진 → 근접도 맵 (+ 16비트 거리, 카메라, raw npz)               scripts/depth.py
2a. 창문    three.js에서 사진을 창문처럼 표시                              examples/portal.js
2b. 배치    사진 자체 3D 공간의 평면과 점                                  scripts/fit_plane.py
3. 확인    실제 사용할 극단적인 시점에서 살펴보기

scripts/와 examples/는 이 스킬 자체 디렉토리 (${CLAUDE_SKILL_DIR}, 플러그인이나 복사된 스킬 모두 동일)를 의미하며, 사용자 프로젝트 디렉토리가 아닙니다. S를 해당 scripts/ 폴더로 설정하고 "$S/depth.py"와 다른 스크립트들을 전체 경로로 실행하세요.

0. 설정 (최초 1회)

먼저 확인: import moge가 작동하는 기존 환경이 있다면 재사용 가능합니다 (사용자에게 위치를 물어보세요). 그렇지 않으면 사용자에게 다운로드 전에 확인을 요청하고, 다운로드할 항목을 명시하세요: PyPI에서 PyTorch 및 도우미 패키지(설치 시 약 1GB), GitHub에서 MoGe 소스와 두 개의 작은 라이브러리(고정 커밋, 수 MB), 그리고 이후 모델 가중치(약 1.3GB, Hugging Face의 Ruicheng/moge-2-vitl). 그런 다음:

"$S/setup.sh" <환경-폴더> --yes

자세한 내용, GPU 참고 사항 및 다른 모델: references/setup.md

1. 깊이

<환경>/.venv/bin/python "$S/depth.py" picture.jpg --out public/depth/ [--dist16] [--npz]
  • 항상 <stem>-near.webp를 씁니다: 근접도(시차), 0은 하늘, 1은 가장 가까운 물체, 물체 가장자리가 2픽셀 확장되어 가장자리가 함께 움직입니다. 1-2K 이미지의 경우 10-25KB.
  • --dist16: <stem>-dist16.webp (16비트 로그 거리, R 상위, G 하위, 무손실)와 <stem>-camera.json (추정된 내부 파라미터). 사진을 표면으로 재구성하는 용도.
  • --npz: fit_plane.py에 사용할 원시 미터법 깊이.
  • --allow-download가 전달되지 않으면 가중치 다운로드를 거부합니다: 사용자에게 먼저 물어보세요.
  • 유효 비율, 깊이 백분위수 및 추정 시야각을 출력합니다. 이를 읽으세요: "valid 20%" 또는 150°의 시야각은 모델이 사진을 이해하지 못했음을 의미합니다.

사진이 변경될 때마다 다시 실행하세요: 이전 버전의 사진에서 추출한 깊이 맵은 모든 가장자리를 잘못 배치합니다.

2a. 창문

examples/portal.js는 자체 포함된 three.js 재질입니다 (프로젝트에 복사하세요). 사진은 정지점 (기본 카메라 위치)에서 본 장면입니다. 다른 위치에서는 유리의 각 픽셀이 시선을 따라 보이는 것을 표시하며, 근접도 맵을 16단계로 탐색하여 가까운 물체가 먼 물체를 가리고 가장자리가 찢어지지 않습니다. 자세한 내용, 튜닝 및 실패 모드: references/portal.md

import { makePortal } from "./portal.js";
const portal = makePortal({ map, near, width: 4, height: 2.5 });
scene.add(portal.mesh); portal.setRest(defaultCameraPosition);
// 매 프레임: portal.update(camera);

examples/portal.html은 단일 파일 데모입니다: 사진, 근접도 맵, portal.js 및 페이지가 포함된 폴더를 서비스하고 portal.html?pic=<파일>&near=<파일>을 열고 포인터를 움직이세요.

실제 보이는 방식으로 확인하세요: 사이트에서 실제 사용하는 가장 왼쪽, 오른쪽, 위쪽, 아래쪽 위치에 카메라를 고정하고 (자동 확인을 위해 데모는 window.__view = [x, y]를 지원합니다) 각각을 살펴보세요:

  • 깊이가 전혀 느껴지지 않나요? 실제 사이트에서 이 효과의 첫 번째 버전이 너무 약해서 눈에 띄지 않았습니다: uQ.y를 낮추세요 (0.6 → 0.4).
  • 가까운 물체가 프레임에 비해 가장 많이 움직이거나 하늘이 흔들리나요? 깊이가 반대입니다 (거리가 근접도로 사용됨).
  • 큰 움직임에서 번지거나 이중으로 보이는 물체: 단일 사진은 가까운 물체 뒤에 아무것도 없습니다. 카메라 움직임을 작게 유지하거나, 완화시키거나 (uEase), 뒷 레이어를 페인팅하세요 (references/placing.md).

2b. 사진 속에 물체 배치하기

<환경>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260
<환경>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260 --corners 415,128 515,124 516,250 414,255
<환경>/.venv/bin/python "$S/fit_plane.py" point out/city-depth.npz 640,700

픽셀은 사진 자체의 좌표입니다 (--norm은 0..1). 출력은 three.js 카메라 공간의 JSON입니다 (카메라가 원점에 있고 -Z 방향을 바라보며, 미터 단위). flatness_rms_m은 영역이 실제로 얼마나 평평한지를 나타냅니다: 40m 떨어진 벽에서 수 센티미터는 평평한 것입니다. 모서리는 패널 자체 가장자리 내부에서 선택하세요 (주변 박스가 아님). 그러면 광고판이 패널의 실제 모양을 따라가며 기울어 보이지 않습니다. 전체 사진을 3D 표면으로 재구성, 찢어진 가장자리, 뒷 레이어: references/placing.md

규칙

  • 라이선스: MoGe-2의 코드와 가중치는 MIT입니다. 여러 인기 있는 깊이 모델은 상업적 사용이 허가되지 않았습니다 (references/setup.md 참조): 클라이언트 또는 작품을 판매하는 포트폴리오를 위해 모델을 변경하기 전에 확인하세요.
  • 사진 자체의 라이선스는 사진에서 파생된 모든 것에 여전히 적용됩니다.
  • 알파 채널의 마스크: 사진이 알파 채널에 마스크(물, 하늘)를 포함하는 경우, WebP를 무손실로 저장하세요 (cwebp -lossless -exact, Pillow exact=True). 손실 알파는 투명 픽셀 아래의 색상을 0으로 만들고 번지게 합니다.
  • 아무것도 다운로드하기 전에 확인을 요청하세요 (패키지, 가중치): 무엇을, 어디서, 얼마나 큰지 명시하세요.

관련 스킬