Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Budowanie i kod

voxelize

/voxelize

Zamienia obraz referencyjny na model MagicaVoxel .vox, porównując sylwetkę i kolory, a potem otwiera go w MagicaVoxel.

Repozytorium
2DtoVoxel ↗
Licencja
MIT
Ostatnia zmiana repozytorium
01.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 01.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Zamienia obraz referencyjny na model MagicaVoxel .vox, porównując sylwetkę i kolory, a potem otwiera go w MagicaVoxel.

Wyzwalacze z opisu

make a voxel model of reference/x.pngturn this into MagicaVoxelvoxelize복셀로 만들어줘매지카복셀 모델로이 그림 복셀로스프라이트 시트 뽑아줘
Oryginalny opis (EN)

Turn a reference image (reference/*.png) into a MagicaVoxel .vox model: study the image, write a build script in models/, iterate against the reference using measured scores (silhouette IoU, colour ΔE) and preview renders, then open it in MagicaVoxel. Also covers quick no-LLM conversion of pixel art (extrude/carve) and game-asset outputs (sprite sheets, OBJ/GLB/PLY, palette variants). Use when the user drops in a reference image or asks for a voxel model, e.g. "make a voxel model of reference/x.png", "turn this into MagicaVoxel", "voxelize", "복셀로 만들어줘", "매지카복셀 모델로", "이 그림 복셀로", "스프라이트 시트 뽑아줘".

Jak działa

  1. 작업 → 명령 (먼저 여기서 고른다)
  2. 1. 관찰 (코드 쓰기 전에)
  3. 2. 빌드 스크립트 — models/<englishslug>.py
  4. 3. 반복 (보통 4~6회) — 점수와 이미지를 함께 본다
  5. 4. 고해상도 마무리 (형태가 잘 맞을 때, 또는 세밀함을 요청받았을 때)
  6. 5. 마무리
  7. 하지 말 것
Sekcje z nagłówków SKILL.md, w oryginale · 108 linii, 1 251 słów
Podgląd SKILL.md
---
name: voxelize
description: >-
  Turn a reference image (reference/*.png) into a MagicaVoxel .vox model: study the image, write a
  build script in models/, iterate against the reference using measured scores (silhouette IoU,
  colour ΔE) and preview renders, then open it in MagicaVoxel. Also covers quick no-LLM conversion
  of pixel art (extrude/carve) and game-asset outputs (sprite sheets, OBJ/GLB/PLY, palette variants).
  Use when the user drops in a reference image or asks for a voxel model, e.g. "make a voxel model of
  reference/x.png", "turn this into MagicaVoxel", "voxelize", "복셀로 만들어줘", "매지카복셀 모델로",
  "이 그림 복셀로", "스프라이트 시트 뽑아줘".
---

# voxelize — 레퍼런스 이미지 → MagicaVoxel 모델

인자: 레퍼런스 이미지 경로 (예: `reference/플레이어의집_레퍼런스.png`). 없으면 `reference/`에서 가장 최근 이미지를
쓰고, 어떤 걸 골랐는지 말한다. 프로젝트에 `CLAUDE.md`가 있으면 그 좌표 규칙과 요령도 따른다. 핵심 규칙:
배열은 `[x, y, z]`이고 **z가 위, y=0이 정면**(MagicaVoxel 기본 카메라가 보는 면). 상자는 위치+크기
`m.box(x, y, z, w, d, h, 색)`, `region=`도 `(x, y, z, w, d, h)` 순서. 색은 `m.pal.add(이름, hex)`로 등록해 이름으로 쓴다.

**필요한 것:** Python 3.10+와 numpy·Pillow·scipy(`pip install 2dtovoxel`, 소스에서는 `pip install -e .`).
MagicaVoxel 0.99.x는 열기·캡처에만 필요하고, 창 캡처(`shot`)는 Windows 전용이다.

**명령 형식:** 아래 `VT`는 voxtool 실행 명령이다 — Windows `py -m voxtool`, macOS/Linux `python3 -m voxtool`,
설치했다면 `voxtool`. UI가 실행한 작업이면 지시문에 적힌 형식을 정확히 그대로 쓴다(권한 규칙과 일치해야 함).

## 작업 → 명령 (먼저 여기서 고른다)

| 요청 | 길 |
|---|---|
| 그림을 정교한 복셀 모델로 | 아래 1~5단계 (스크립트 작성 + 점수 기반 반복) |
| 더 세밀하게 / 고해상도로 | 기존 스크립트에 `RES` 적용 → 4단계 (`paint_reference`, `--res`, `--zoom`) |
| 픽셀아트·아이콘을 바로 두께 있는 복셀로 | `VT extrude <img> --name N [--depth 4 --inflate]` → 필요하면 2단계부터 다듬기 |
| 정면/측면/윗면 실루엣 그림 | `VT carve --front f --side s --top t --name N` → 다듬기 (측면·윗면은 자동으로 `EXTRA_REFERENCES`) |
| 같은 물체를 여러 방향에서 본 그림·렌더 여러 장 | 가장 잘 보이는 한 장을 `REFERENCE`, 나머지를 `EXTRA_REFERENCES`로 → 1~5단계 |
| 기존 모델 수정 | 스크립트 수정 → `VT build models/N.py` → 3단계 반복 |
| 게임 에셋 | `VT sprites models/N.py --dirs 8`, `VT export models/N.py --format glb\|obj\|ply`, `VT recolor ...` |

## 1. 관찰 (코드 쓰기 전에)
1. 이미지를 직접 본다(Read).
2. `VT ref cutout <img>` → 배경이 제대로 지워졌는지 확인(점수 계산의 기준이 된다). 물체가 여러 개인 키트
   시트면 `--keep all`, 그리고 스크립트에 `CUTOUT = {"keep": "all"}`.
3. `VT ref grid <img>`로 좌표를 읽고, `VT ref crop <img> x0 y0 x1 y1 --zoom 3`으로 영역별로 확대한다.
4. `VT ref palette <img>`, `VT ref sample <img> x,y x,y ...`로 재질별 실제 색을 얻는다.
5. 구성요소 목록: 본체, 지붕, 개구부, 장식, 조명, 식물, 바닥/계단. 보이지 않는 면은 보이는 면에 맞춰 단순히.
6. 스케일: 크기를 아는 요소 하나(보통 문 ≈ 20 voxel)를 기준으로 비율 환산. 설계는 보통 100 안팎으로 잡는다
   (세밀함은 마지막에 `RES`로 올린다. 축별 256을 넘는 격자는 저장할 때 자동으로 조각 나뉨).

## 2. 빌드 스크립트 — `models/<english_slug>.py`
- docstring에 레이아웃 요약. `NAME`, `REFERENCE`, `VIEW = {"azimuth", "elevation", "fov"}`, `build() -> Model`.
- 맨 위에 `RES = 1`을 두고 `Model(W, D, H, seed=..., res=RES)`로 만든다. 좌표는 전부 설계 단위로 쓰고, `m.v`를
  직접 다루는 헬퍼만 복셀 단위(`m.res`를 곱함)라는 점에 주의. 그래야 4단계에서 해상도를 올릴 수 있다.
- 주요 치수는 상단 상수로, 좌표는 상수에서 유도. 반복 요소는 함수로. 색은 이름으로 등록(기본색 ≈ 정면 샘플 ÷ 0.9).
- 조각이 여러 개면 `with m.part("name"):`. 변환 결과를 바탕으로 쓸 때는 `Model.from_vox(...)`/`m.paste_vox(...)`.
- **나무·덤불·이끼 같은 자연물**은 `ellipsoid`/`blob`이나 직접 만든 잎 뭉치 헬퍼 대신 라이브러리의 식물 도구를 쓴다:
  줄기·가지·뿌리는 `m.tube(점들, 반지름들, 껍질색들)`, 수관은 레퍼런스 외곽에서 잰 잎 덩어리로
  `m.foliage([(cx, cy, cz, r), ...], [어두운→밝은 잎색들], tips=밝은색)`, 한 그루 통째로는 `m.tree(..., style=...)`
  (`round` `column` `cone` `tiered` `branched` `spread`, 또는 `lobes=`). 줄기·가지를 먼저 그리고 잎을 나중에.
  레퍼런스가 복셀 그림이면 잎 정육면체 하나 = 복셀 하나가 되게 크기를 잡는다(`clump`는 뭉치 반지름, 복셀 단위).
  비율이 맞은 뒤에는 `m.carve_to_reference(REFERENCE, VIEW, only=잎색들, cutout=CUTOUT)`로 실루엣 밖 잎을 깎는다.
- **그림에서 잰 잎 덩어리는 한 평면 위에 있다.** 그대로 쓰면 옆에서 볼 때 납작한 판이 된다. 반드시
  `m.crown_depth(덩어리들, 줄기x, 줄기y, VIEW)`로 깊이를 채우거나 `m.tree(..., lobes=덩어리들, view=VIEW)`를 쓴다.
  **금지:** 실루엣의 빈 곳을 카메라를 향한 평면에 복셀 한 겹으로 채우기, 잎 덩어리를 카메라 시선 방향으로 복사하기
  (수관이 비스듬히 기운 판이 된다). 정면 점수는 조금 오르지만 3D로 보면 망가진다.
- 참고 예시: `models/player_house.py`.
- 첫 빌드 뒤 `VT fit-camera models/<slug>.py`로 카메라를 맞추고 출력된 `VIEW = {...}`를 스크립트에 넣는다.
- **같은 물체의 그림이 여러 장이면** 나머지는 그 그림을 본 카메라와 함께 `EXTRA_REFERENCES = [("reference/x_side.png",
  {"azimuth": 90, "elevation": 0}), ...]`에 넣는다. 정사영 도면이면 정면 0, 왼쪽 90, 뒤 180, 오른쪽 270, 위에서 본 그림은
  `"elevation": 90`. 렌더·사진처럼 각도를 모르면 `VT fit-camera models/<slug>.py --ref 1`(첫 번째 추가 그림)로 찾는다.
  빌드가 그림마다 점수를 따로 낸다. 보이지 않던 면을 추측하지 않고 맞출 수 있으니 있으면 꼭 쓴다.

## 3. 반복 (보통 4~6회) — 점수와 이미지를 함께 본다
1. `VT build models/<slug>.py` → 출력의 `score: iou=… dE=… worst: …` 를 읽는다.
   - iou = 레퍼런스와 실루엣 겹침(1이 완벽), dE = 색 차이(낮을수록 좋음), worst = 가장 어긋난 영역.
   - `EXTRA_REFERENCES`가 있으면 그림마다 `score <파일>: …` 줄과 평균(`score all N views`)이 더 나온다. 모두 본다.
2. `output/<slug>/<slug>_score.png`(빨강 = 빠짐, 파랑 = 넘침), `_compare.png`, `_sheet.png`를 Read로 본다.
3. 우선순위대로 고친다: 카메라 → 전체 비율 → 실루엣(빨강/파랑 영역) → 색 → 디테일. 한 번에 고치고 다시 빌드.
4. stats의 색별 개수로 빠진 요소 확인(0개면 버그).
5. 점수는 레퍼런스 방향 하나만 잰다(추가 그림이 없으면). 그래서 빌드는 점수가 못 보는 것도 따로 알려 준다:
   - `_turn.png` — 레퍼런스 방향부터 90°씩 돌린 네 장. 매번 본다.
   - `depth: 0.85` — 물체마다 높이 구간별 (앞뒤 깊이 ÷ 너비)의 중앙값. `(thin)`(0.5 미만)이면 옆에서 보면 판이라는 뜻이다.
     간판·울타리·벽 패널처럼 원래 얇은 물체가 아니면 고친다(나무 수관은 `crown_depth`).
   - `loose: 2 pieces, …` — 자기 물체(part)의 나머지와 닿지 않은 덩어리와 그 위치(설계 단위). 줄기에서 떨어진 잎,
     벽 위에 뜬 지붕, 깎다 남은 부스러기가 여기 걸린다. 이어 붙이거나, 부스러기면 `m.remove_loose()`(기본: 8칸 이하만,
     `max_voxels=None`이면 전부)를 `paint_reference` 앞에서 부른다. 따로 떨어진 소품이면 `with m.part("이름"):`으로
     자기 물체로 만든다. 불꽃·반딧불처럼 일부러 띄운 것은 그대로 둔다.
   자연물(나무·덤불)은 마무리 전에 `VT angles models/<slug>.py <az+90>,20 <az+180>,20`으로도 옆·뒤에서 둥근지 확인한다.
6. 세부는 320 px 점수로는 안 보인다. `VT score models/<slug>.py --zoom <worst 영역>`(예: `top-right`, 또는
   `ref grid`로 읽은 `x0,y0,x1,y1`)으로 그 영역을 레퍼런스 원래 해상도로 확대해 보고 고친다.

**멈춤 기준 (게이트):**
- 점수가 두 번 연속 오르지 않으면 반복을 멈추고, 남은 차이를 보고한다.
- 점수는 "관찰"이다. 원근 레퍼런스와 정사영 렌더의 차이처럼 점수로는 줄일 수 없는 차이가 있다 —
  그럴 때는 숫자를 억지로 올리지 말고 보이는 핵심 요소(문·창 등)가 가려지지 않는 쪽을 택한다.
- 레퍼런스가 없거나 cutout이 비면 점수는 "확인 불가"로 두고 이미지 비교만으로 진행했다고 밝힌다.

## 4. 고해상도 마무리 (형태가 잘 맞을 때, 또는 세밀함을 요청받았을 때)
반복은 `RES = 1`로 빠르게 하고, 이 단계는 형태가 확정된 뒤 한두 번만 한다(고해상도로는 비율이 고쳐지지 않는다).
1. `build()`의 마지막 줄(`return m` 앞)에 `m.paint_reference(REFERENCE, VIEW)` — 레퍼런스에 보이는 복셀을 그 픽셀 색으로
   칠한다(명암·얼룩·무늬). `VIEW`는 fit-camera로 맞춘 카메라여야 한다(`SCORE_VIEW`가 있으면 그것). IoU 0.95 이상일 때
   효과가 좋고, 덜 맞으면 얼룩진다. 재질 사이 번짐은 `tol`(기본 30)이 막는다. 특정 재질만 칠하려면 `only=[...]`.
2. `VT build models/<slug>.py --res 2`(또는 3)로 같은 스크립트를 더 고운 복셀로 시험한다. 레퍼런스가 이미 복셀 그림이고
   그 칸 크기에 맞춰 만들었다면 해상도를 올리지 않는다(잎이 그림보다 잘게 쪼개져 오히려 덜 닮는다). 복셀이 수백만 개면 빌드에
   수십 초 걸린다. 결과가 좋으면 스크립트의 `RES`를 그 값으로 바꾸고 한 번 더 빌드한다 — `--res`는 그 빌드에만
   적용되므로, 그대로 두면 나중에 다시 빌드할 때(UI의 Rebuild 포함) 1배로 돌아간다.
3. dE가 줄었는지, `--zoom`으로 핵심 영역이 나아졌는지 확인한다. 나빠졌으면 paint 줄을 빼거나 `only`/`tol`을 조정한다.
   UI 작업이면 이 빌드들도 빌드 횟수에 들어간다.

## 5. 마무리
1. (대화형일 때만) `VT build models/<slug>.py --open` → MagicaVoxel에서 열고, Windows면 `VT shot`으로 로드 확인.
2. 보고: .vox 경로, 최종 점수(iou/dE)와 처음 대비 변화, 비교 이미지, 의도적 타협, Render 탭에서 조명이 빛난다는 점.

## 하지 말 것
- 다른 모델을 빌드하지 않는다 — 그 모델의 .vox(사용자의 MagicaVoxel 편집이 있을 수 있음)를 덮어쓴다.
  (빌드는 MagicaVoxel에서 저장된 파일을 `_edited_<시각>.vox`로 백업하지만, 기대지 말 것.)
- 공용 라이브러리(`voxtool/`), `CLAUDE.md`, `.claude/`를 작업 중에 고치지 않는다. 필요한 기능은 모델 스크립트 안에.
- 점수를 올리려고 레퍼런스에 없는 형태를 만들거나 렌더/점수 코드를 우회하지 않는다. 레퍼런스 방향에서만 맞고
  다른 방향에서는 납작한 형태(카메라를 향한 평면 채우기, 시선 방향 복사)도 점수 우회다.
- `python -c` 같은 임시 코드로 파이프라인 단계를 대신하지 않는다. voxtool 명령으로 안 되는 일이면 보고한다.

Wersje

W bazie nie ma innych skilli o nazwie voxelize.

Migawka bazy z 13.11.2026 · wersja paczki 0a149d762742 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90pixel-art
    Zamienia obraz referencyjny w pixel art 64x64 z bramkami akceptacji i zapisuje wynik jako HTML, PNG i SVG, z tłem i bez tła.
  • 100world-builder
    Zamienia brief w edytowalne otoczenie voxelowe albo zestaw modułowych zasobów w Voxel Worlds i eksportuje pliki GLB i VOX.
  • 96truepixel
    Zamienia obraz pixel art wygenerowany przez AI w czysty sprite: jeden piksel na komórkę, mała paleta i przezroczyste tło.
  • 100pixel-run
    Zamienia obraz referencyjny postaci w zapętlony cykl biegu w pixel art: przezroczysty GIF, arkusz sprite'ów 4x4 (16 klatek) w PNG i archiwum ZIP z pojedynczymi klatkami.
  • 100build-minecraft-model-from-image
    Zamienia zdjęcie przedmiotu w model 3D w stylu Minecraft z kilku prostopadłościanów i pikselowych tekstur.
  • 100scenario-3d
    Generuje i obsługuje zasoby 3D przez serwer MCP Scenario: siatki z tekstu lub obrazu, pliki GLB, FBX, OBJ, STL i VOX, tekstury PBR, remesh, UV, auto-rigging i retargeting animacji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.