경량 통합본 안내: 이 ZIP에는 Blender 편집 파일을 담고 GLB는 제외했습니다. 아래 GLB 설명과 검사 기록은 별도로 제작·검증한 원본 교환 파일에 대한 내용입니다.

# 경복궁 근정전 · 복셀 디자인

0.25m 정규 정육면체 격자 위에서 새로 조립한 근정전 외관 해석 디자인입니다. 확정 일반 3D 모델의 치수·배치·지붕 제어면을 입력으로 사용했습니다. 실측 스캔, 문화유산 보수용 도면, 구조설계 또는 제조용 데이터가 아닙니다.

## 파일

- `Geunjeongjeon_voxel_editable.blend`: 재질·부위 컬렉션·카메라를 편집할 수 있는 Blender 원본
- `Geunjeongjeon_voxel.glb`: 컬러 재질 포함 교환용 모델, 배경·카메라 제외
- `voxel_grid.npz`: 정규 격자의 원시 점유 및 부위/색상 값
- `palette_and_design.json`: 16색 sRGB 팔레트(현재14색 사용), 격자 크기, 해석 선택, 부위 목록
- `source_controls.json`, `source_details.npz`, `source_details_index.json`: 확정 일반 모델에서 추출한 자체 제작 형상 입력. 외부 사진이나 실측보고서 원문은 포함하지 않음
- `scripts/build_voxel.py`: 외부 유료 API, 애드온, 추가 설치 없이 Blender와 기본 NumPy로 재생성
- `renders/`: 전·후·동·서·상부, 사선, 상세와 일반 모델 비교
- `validation/technical_validation.json`: 저장 후 재열기·격자·축정렬 면·정상 좌표·GLB 재가져오기 검사

## 열기와 편집

Blender 4.3.2에서 제작했습니다. `.blend`를 열면 사선 카메라가 기본 뷰입니다. 아웃라이너의 01~15 번호 컬렉션은 부위별 표면 메시입니다. 각 메시에는 16색 팔레트가 들어 있으며 실제 표면에는14색이 쓰였습니다. 재질을 바꾸면 해당 색상 전체를 바꿀 수 있고, 편집 모드에서 개별 면을 선택할 수 있습니다.

월대·계단·기둥·창호·보/서까래·하/상층 공포·하/상층 지붕·마루/잡상·석난간·현판·참고고주가 구분됩니다. 90은 렌더 배경과 조명, 91은 검토 카메라이며 GLB에는 포함하지 않습니다.

원점은 본채 주열 평면 중심, 지면 Z=0입니다. X=동, Y=북, Z=위, 정면은 -Y이며 1 Blender 단위=1m입니다. GLB 표준의 Y-up 변환은 내보내기에서 처리됩니다.

## 격자와 최적화

- 모든 건축 모델 꼭짓점은 **0.25m** 배수의 한 격자에 놓입니다
- 곡선, 대각선, 원기둥은 축정렬 블록과 계단형 윤곽으로 바뀝니다
- 부드러운 쉐이딩, 모서리 베벨, 숨겨진 매끈한 지붕면은 사용하지 않았습니다
- 약 69.3만 개 점유 셀을 개별 오브젝트로 만들지 않고, 노출 면을 재질별로 greedy 병합합니다. 정확한 최종 통계는 build_stats.json에 있습니다
- 표면은 부위별 메시 13개입니다. 큰 평면을 병합해도 꼭짓점·엣지는 격자에 정렬되며 계단형 지붕 실루엣이 유지됩니다
- 내부가 전부 채워진 솔리드 지붕이 아니라 원본 지붕면을 샘플링한 두께 3셀(0.75m 이내)의 계단형 복셀 쉘입니다. 상층 바닥은 만들지 않았습니다
- 보통 위치의 반올림 경계 오차는 축당 최대 0.125m입니다. 얇은 부재는 읽히도록 최소 한 칸으로 확장되어 더 큰 국부 오차가 생깁니다. 지붕은 셀 중심 샘플이므로 경계/경사 오차도 있습니다

## 보존한 정체성

일반 3D 모델의 비균등 5×5칸 주열, 외진기둥20개·안쪽/귀고주16개 배치, 낮은 상층 창호 띠, 상하 지붕의 유사한 폭, 큰 상층 팔작 합각, 얕은 하층 지붕 띠, 처마의 수직 상승과 평면 굽이, 긴 용마루와 양끝 취두를 재사용했습니다.

각 귀마루에는 7개의 작은 잡상 실루엣을 배치했습니다. 붉은 기둥, 녹청 공포와 창호, 회색 기와, 밝은 두 단 월대, 중앙 답도와 좌우 계단, 전면이 넓게 비고 본채가 뒤로 치우친 월대 배치를 남겼습니다.

## 사실과 제작 해석을 구분합니다

문헌·실측도 기반 사실: 정면/측면5칸, 통층 실내, 두 단 월대, 주요 주열 치수, 비균등 칸폭, 외3출목·내4출목, 공포군 반복 수, 귀마루7잡상 등입니다. 일반 모델이 해당 사실을 해석한 기하를 복셀 입력으로 사용했습니다.

해석/평균화: 지붕 곡면 제어점과 처짐, 개별 부재 단면, 석재의 불규칙성, 월대의 직사각 평균형, 두 월대 사이 전후 여유, 조각/채색의 세부입니다. 원자료의 주된 치수는 1996/2000 기록이며 현재의 정밀 측량을 뜻하지 않습니다.

복셀 고유의 추상화 손실:
- 둥근 기둥은 사각 블록 단면으로 바뀝니다
- 창호 꽃살은 규칙적인 녹색 격자 패턴으로 대체됩니다
- 단청의 꽃/선 문양은 16색 블록 리듬으로 줄였습니다. 사진을 텍스처로 사용하지 않았습니다
- 기와 한 장 한 장과 곡선 소로/쇠서의 미세 조각은 합쳐집니다
- 잡상은 2~3블록 높이의 해석 실루엣입니다. 각 인물/동물의 세부 조각은 복원하지 않았습니다
- 현판의 실제 한자 서체는 해상도 한계로 읽을 수 없으며, 세 개의 금색 표식으로 표현했습니다. 진짜 글자나 정확한 현판 복제가 아닙니다
- 봉황 답도 부조, 석난간 동물상 세부, 드므, 어좌·일월오악도·닫집·반자·정밀 내부 결구는 포함하지 않습니다

원본처럼 지붕과 부재를 서로 관통시키는 구성은 격자 점유를 한 번 정리하여 겹치는 내부 면을 제거했습니다. 부위 경계에서 내부 면이 생략되며, greedy 면은 T접점을 가질 수 있습니다. 따라서 컬렉션을 분리했을 때 절단면이 자동으로 닫히지 않습니다. 바로 3D 프린트하는 일체형 폐합/매니폴드 모델이 아닙니다.

## 재생성

압축 파일을 풀고 Blender가 설치된 환경에서 다음을 실행합니다.

    VOXEL_STAGE=final blender -b -t 2 --python scripts/build_voxel.py

기본값은 blockout이며 사선과 정면을 16샘플로 렌더합니다. final은7개 뷰를 48샘플로 렌더합니다. 코드 상단의 G는 공통 격자 크기입니다. 현재 셀 개수·구성은 0.25m를 전제로 검수했으므로 다른 크기로 바꾸면 구도와 디테일 검토가 다시 필요합니다.

`voxel_grid.npz`의 labels 값은 `컬렉션 번호*32+팔레트 인덱스`이며 0은 빈 공간입니다. `source_*` 입력만으로 현재 복셀을 재생성할 수 있고 일반모델 `.blend`나 외부 원문이 필요하지 않습니다. extract_source.py/extract_details.py는 입력을 새로 추출하는 개발 보조 도구이며 별도 일반 모델 스냅샷이 필요합니다.

## 기술 검증과 렌더 주의

최종 형상은 저장 후 다시 열고 GLB로 내보낸 뒤 재가져오기하여 점검했습니다. 최종 통계와 PASS 여부는 `validation/technical_validation.json`에 있습니다. 원본 지붕면 28,368개 셀 중심 샘플에서 점유 누락과 인접 지붕 높이 구간의 단절을 검사합니다. 바깥 실루엣은 그대로 두고 내부 두께를 확보해 경사층 사이 틈을 막았습니다.

강한 측광에서는 복셀 계단 모서리의 작은 그림자가 점처럼 보일 수 있습니다. 최종 렌더는 넓은 면광원을 사용합니다. 매끈한 지붕을 덧붙여 이를 숨기지 않았습니다.

## 근거와 출처

실사진은 관찰에만 사용했고 이 번들에는 원본 사진/도면/PDF를 넣지 않았습니다. 일반 모델과 복셀 렌더는 자체 제작 형상에서 생성했습니다.

- 국가유산청 국가유산포털, 경복궁 근정전: https://www.heritage.go.kr/heri/cul/culSelectDetail.do?ccbaCpno=1111102230000&pageNo=1_1_2_0
- 국가유산청 정면 사진(공공누리1, 사진6400271): https://www.heritage.go.kr/heri/cul/imgHeritage.do?ccimId=6400271&ccbaKdcd=11&ccbaAsno=0002230000000&ccbaCtcd=11
- 국가유산청 공포·현판 사진(공공누리1, 사진1611709): https://www.heritage.go.kr/heri/cul/imgHeritage.do?ccimId=1611709&ccbaKdcd=11&ccbaAsno=0002230000000&ccbaCtcd=11
- 국가유산청 코너 사선 사진(공공누리1, 사진1611718): https://www.heritage.go.kr/heri/cul/imgHeritage.do?ccimId=1611718&ccbaKdcd=11&ccbaAsno=0002230000000&ccbaCtcd=11
- 국가유산청 개별1층평면도(보수), 공공누리1: https://www.heritage.go.kr/heri/cul/chartImgHeritage.do?file_seq=2839335
- 문화재청, 근정전 실측조사보고서(하),2000. 치수·구조 사실관계 참고: https://heritage.go.kr/heri/cul/linkSelectEbookDetail.do?bbsId=BBSMSTR_1021&nttId=19132&pageNo=2_4_1_1
  이 보고서는 공공누리4이며 원문 PDF/그림은 재배포하지 않습니다. 보고서 그림이나 사진 픽셀을 모델/재질/이 번들에 포함하지 않았습니다.
- 공공누리1 조건: https://www.kogl.or.kr/info/licenseType1.do

일반 모델 고정 입력 SHA256: `1c0cda3877fd3ea2d011fc4c6f92a689669b2b1b742e9426095daf68076899d4`
이후 일반모델 담당이 현판의 면적0 폴리곤을 제거하고 카메라/메타데이터를 고쳤습니다. 보이는 구조 변경은 없으며 이 복셀의 입력 형상에는 영향을 주지 않습니다.

제작/검토일: 2026-10-04