ReconstructFull API

ReconstructFull은 가장 간단하고 사용하기 쉬운 전체 복원 인터페이스로, 빠른 프로젝트 시작과 신규 사용자에게 적합합니다. 이미지 메타데이터 추출, 항공삼각측량 계산, 3D 복원의 완전한 워크플로우를 자동으로 처리합니다.

🎯 인터페이스 특징

• ✅ 높은 자동화 수준: 이미지 EXIF에서 GPS와 카메라 정보를 자동 읽기
• ✅ 간단한 구성: 최소 요구사항은 이미지 경로 제공만
• ✅ 올인원: 이미지에서 직접 최종 결과물 생성
• ✅ 지능적 최적화: 최적의 처리 매개변수를 자동 선택

📋 매개변수 상세

필수 매개변수

매개변수명	타입	설명	예시값
license_id	int	SDK 라이센스 ID	9200
working_dir	string	작업 디렉토리 경로	"C:/Projects/MyProject"
gdal_folder	string	GDAL 데이터 디렉토리	"C:/MipMap/SDK/data"
coordinate_system	object	입력 좌표계	아래 설명 참조
image_meta_data	array	이미지 목록	아래 설명 참조
input_image_type	int	이미지 타입	1=RGB, 2=다중분광, 3=적외선
resolution_level	int	정밀도 수준	1=높음, 2=중간, 3=낮음

선택적 매개변수 - 출력 제어

매개변수명	타입	기본값	설명
generate_obj	bool	false	OBJ 형식 모델 생성
generate_ply	bool	false	PLY 형식 모델 생성
generate_osgb	bool	false	OSGB 형식 생성 (경사 사진)
generate_3d_tiles	bool	false	3D Tiles 생성 (Cesium)
generate_las	bool	false	LAS 점군 생성
generate_pc_ply	bool	false	점군 PLY 생성
generate_pc_osgb	bool	false	점군 OSGB 생성 (LOD)
generate_pc_pnts	bool	false	점군 PNTS 생성 (3D Tiles)
generate_geotiff	bool	false	정사영상 생성
generate_tile_2D	bool	false	2D 타일 생성
generate_2D_from_3D_model	bool	false	3D 모델에서 정사영상 생성

선택적 매개변수 - 좌표계

매개변수명	타입	기본값	설명
coordinate_system_3d	object	Local/LocalENU	출력 3D 좌표계
coordinate_system_2d	object	LocalENU	출력 2D 좌표계

선택적 매개변수 - 고급 기능

매개변수명	타입	기본값	설명
gcp_path	string	-	기준점 파일 경로
gcp_coor_sys	object	-	기준점 좌표계
use_image_position_constraint	bool	true	이미지 위치 제약 사용
fast_mode	bool	false	고속 모드 (품질 저하)
min_avali_memory_size	float	16.0	최소 사용 가능 메모리 (GB)
output_block_change_xml	bool	false	Block Exchange XML 출력

📝 데이터 구조 상세

coordinate_system 객체

{
  "type": 2,              // 1=투영, 2=지리, 3=지심
  "type_name": "Geographic",
  "label": "WGS 84",     // 좌표계 명칭
  "epsg_code": 4326      // EPSG 코드
}

image_meta_data 배열 요소

기본 형식 (EXIF 자동 읽기)

{
  "id": 1,                           // 고유 식별자
  "path": "C:/Images/DJI_0001.JPG",  // 이미지 경로
  "group": "camera_1"                // 선택사항: 카메라 그룹
}

완전 형식 (사용자 정의 메타데이터)

{
  "id": 1,
  "path": "C:/Images/IMG_0001.JPG",
  "group": "nadir",                  // 카메라 그룹명
  "meta_data": {                     // 사용자 정의 메타데이터
    "width": 6000,                   // 이미지 너비 (픽셀)
    "height": 4000,                  // 이미지 높이 (픽셀)
    "pos": [114.123456, 22.123456, 100.5],  // [경도, 위도, 고도]
    "pos_sigma": [0.05, 0.05, 0.10], // [X정밀도, Y정밀도, Z정밀도] (미터)
    "focal_length": 24.0,            // 초점거리 (밀리미터)
    "pixel_size": 0.00391            // 픽셀 크기 (밀리미터)
  }
}

카메라 그룹화 (group) 매개변수

다중 카메라 시스템용으로, 서로 다른 카메라의 이미지를 그룹으로 처리:

"image_meta_data": [
  {"id": 1, "path": "nadir/IMG_001.jpg", "group": "nadir"},
  {"id": 2, "path": "nadir/IMG_002.jpg", "group": "nadir"},
  {"id": 3, "path": "oblique_f/IMG_001.jpg", "group": "oblique_forward"},
  {"id": 4, "path": "oblique_b/IMG_001.jpg", "group": "oblique_backward"},
  {"id": 5, "path": "oblique_l/IMG_001.jpg", "group": "oblique_left"},
  {"id": 6, "path": "oblique_r/IMG_001.jpg", "group": "oblique_right"}
]

일반적인 그룹화 시나리오:

• 5목 경사 카메라: nadir, oblique_forward, oblique_backward, oblique_left, oblique_right
• 듀얼 카메라 시스템: wide_angle, telephoto
• 다중기 협업: drone_1, drone_2, drone_3
• 다중 시상: morning, afternoon

pos와 pos_sigma 매개변수 설명

pos 매개변수:

• 형식: [경도, 위도, 고도] 또는 [X, Y, Z] (좌표계에 따라)
• 단위: 지리좌표계는 도와 미터, 투영좌표계는 미터
• 용도: EXIF의 GPS 정보 재정의 또는 GPS 없는 이미지에 위치 제공

pos_sigma 매개변수:

• 형식: [σ_X, σ_Y, σ_Z]
• 단위: 미터
• 의미: 각 방향의 위치 측정 표준편차 (1σ)
• 용도: 항공삼각측량 최적화에서 가중치로 사용, 정밀도가 높을수록 (σ가 작을수록) 가중치가 큼

일반적인 값:

측위 방식	σ_X/σ_Y	σ_Z	설명
RTK 고정해	0.02-0.05m	0.05-0.10m	최고 정밀도
PPK 후처리	0.03-0.08m	0.08-0.15m	고정밀도
일반 GPS	2-5m	3-8m	표준 정밀도
수동 추정	0.5-2m	1-3m	저정밀도

📝 구성 예시

최소 구성

{
  "license_id": 9200,
  "working_dir": "C:/Projects/QuickStart",
  "gdal_folder": "C:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 2,
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  "image_meta_data": [
    {"id": 1, "path": "C:/Images/DJI_0001.JPG"},
    {"id": 2, "path": "C:/Images/DJI_0002.JPG"},
    {"id": 3, "path": "C:/Images/DJI_0003.JPG"},
    {"id": 4, "path": "C:/Images/DJI_0004.JPG"},
    {"id": 5, "path": "C:/Images/DJI_0005.JPG"}
  ],
  "generate_obj": true,
  "generate_geotiff": true
}

다중 카메라 그룹 구성 예시

{
  "license_id": 9200,
  "working_dir": "D:/Projects/MultiCamera",
  "gdal_folder": "D:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 1,
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  
  // 다중 카메라 이미지 그룹화
  "image_meta_data": [
    // 수직 카메라
    {"id": 1, "path": "nadir/IMG_001.jpg", "group": "nadir"},
    {"id": 2, "path": "nadir/IMG_002.jpg", "group": "nadir"},
    
    // 전방 경사 카메라
    {"id": 3, "path": "forward/IMG_001.jpg", "group": "oblique_f"},
    {"id": 4, "path": "forward/IMG_002.jpg", "group": "oblique_f"},
    
    // 더 많은 카메라 그룹...
  ],
  
  "generate_osgb": true,
  "generate_3d_tiles": true
}

사용자 정의 POS 구성 예시

{
  "license_id": 9200,
  "working_dir": "D:/Projects/PPK_Project",
  "gdal_folder": "D:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 1,
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  
  // 고정밀 PPK 후처리 위치 데이터 사용
  "image_meta_data": [
    {
      "id": 1,
      "path": "images/DJI_0001.JPG",
      "meta_data": {
        "width": 5472,
        "height": 3648,
        "pos": [114.305421, 22.596013, 120.543],  // PPK 처리 후 정밀 위치
        "pos_sigma": [0.03, 0.03, 0.05]  // PPK 정밀도
      }
    },
    {
      "id": 2,
      "path": "images/DJI_0002.JPG",
      "meta_data": {
        "width": 5472,
        "height": 3648,
        "pos": [114.305512, 22.596089, 120.621],
        "pos_sigma": [0.03, 0.03, 0.05]
      }
    }
    // ... 더 많은 이미지
  ],
  
  "generate_obj": true,
  "generate_geotiff": true
}

완전 구성 예시 (GCP 포함)

{
  "license_id": 9200,
  "working_dir": "D:/Projects/HighPrecision",
  "gdal_folder": "D:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 1,
  
  // 입력 좌표계 - WGS84
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  
  // 출력 좌표계 - UTM
  "coordinate_system_3d": {
    "type": 3,
    "label": "WGS 84 / UTM zone 50N",
    "epsg_code": 32650
  },
  
  // 기준점
  "gcp_path": "D:/Projects/HighPrecision/gcps.txt",
  "gcp_coor_sys": {
    "type": 3,
    "label": "WGS 84 / UTM zone 50N",
    "epsg_code": 32650
  },
  
  // 이미지 목록
  "image_meta_data": [
    {"id": 1, "path": "D:/Data/flight1/IMG_001.JPG"},
    {"id": 2, "path": "D:/Data/flight1/IMG_002.JPG"},
    // ... 더 많은 이미지
  ],
  
  // 모든 형식 출력
  "generate_obj": true,
  "generate_osgb": true,
  "generate_3d_tiles": true,
  "generate_las": true,
  "generate_geotiff": true,
  "generate_tile_2D": true
}

💾 출력 구조

처리 완료 후 작업 디렉토리에 다음 구조가 생성됩니다:

working_dir/
├── products/              # 최종 성과물
│   ├── models/           # 3D 모델
│   │   ├── model.obj    # OBJ 형식
│   │   ├── model.mtl    # 재질 파일
│   │   ├── textures/    # 텍스처 이미지
│   │   └── tileset.json # 3D Tiles
│   ├── pointcloud/       # 점군 데이터
│   │   └── cloud.las    # LAS 형식 점군
│   └── orthophoto/       # 정사영상
│       ├── ortho.tif    # GeoTIFF
│       └── tiles/       # 타일 데이터
├── milestones/           # 중간 결과
│   ├── at_result/       # 항공삼각측량 결과
│   ├── roi.json         # ROI 범위
│   └── report.html      # 처리 보고서
└── log/                  # 로그 파일
    └── log.txt          # 상세 로그

🎯 사용 제안

적합한 시나리오

• ✅ 빠른 프로토타입 및 테스트
• ✅ 표준 항공 촬영 프로젝트
• ✅ 자동화 일괄 처리
• ✅ 초보자 학습

부적합한 시나리오

• ❌ 처리 매개변수의 세밀한 제어 필요
• ❌ 기준점 사용 필요
• ❌ 중간 결과 확인 필요
• ❌ 특수 카메라나 센서

🔧 고급 기법

1. 다중 프로젝트 일괄 처리

import json
import subprocess
from pathlib import Path

def batch_process(project_list):
    for project in project_list:
        # 구성 생성
        config = {
            "license_id": 9200,
            "working_dir": f"./output/{project['name']}",
            "gdal_folder": "./data",
            "coordinate_system": {"type": 2, "epsg_code": 4326},
            "image_meta_data": [
                {"id": i+1, "path": str(img)} 
                for i, img in enumerate(project['images'])
            ],
            "input_image_type": 1,
            "resolution_level": 2,
            "generate_obj": True,
            "generate_geotiff": True
        }
        
        # 구성 저장
        config_path = f"./config_{project['name']}.json"
        with open(config_path, 'w') as f:
            json.dump(config, f, indent=2)
        
        # 처리 실행
        subprocess.run([
            "reconstruct_full_engine.exe",
            "-reconstruct_type", "0",
            "-task_json", config_path
        ])

2. 자동 매개변수 최적화

def optimize_parameters(image_count, available_memory_gb):
    """프로젝트 규모에 따라 매개변수 자동 선택"""
    
    # 해상도 수준
    if image_count < 100:
        resolution_level = 1  # 고정밀도
    elif image_count < 500:
        resolution_level = 2  # 중정밀도
    else:
        resolution_level = 3  # 저정밀도 (대형 프로젝트)
    
    # 출력 형식
    if available_memory_gb > 32:
        formats = {
            "generate_obj": True,
            "generate_osgb": True,
            "generate_3d_tiles": True,
            "generate_las": True
        }
    else:
        formats = {
            "generate_obj": True,
            "generate_las": False
        }
    
    return resolution_level, formats

3. 진행률 모니터링

import re
import time
from threading import Thread

def monitor_progress(log_file):
    """처리 진행률 모니터링"""
    
    def read_progress():
        with open(log_file, 'r') as f:
            f.seek(0, 2)  # 파일 끝으로 이동
            while True:
                line = f.readline()
                if line:
                    match = re.search(r'\[PROGRESS\] (\d+)%', line)
                    if match:
                        progress = int(match.group(1))
                        print(f"\r진행률: {'█' * (progress//2)}{'░' * (50-progress//2)} {progress}%", end='')
                time.sleep(0.1)
    
    thread = Thread(target=read_progress, daemon=True)
    thread.start()

❓ 자주 묻는 질문

Q: 왜 일부 이미지가 사용되지 않았나요?

A: ReconstructFull은 품질이 나쁜 이미지를 자동으로 필터링합니다:

• 흐린 이미지
• GPS 정보가 없는 이미지
• 중복되거나 유사도가 높은 이미지

로그에서 필터링된 이미지와 그 이유를 확인할 수 있습니다.

Q: GPS가 없는 이미지를 처리하려면?

A: GPS 정보가 없는 이미지의 경우:

1. ReconstructAT 인터페이스 사용 (GPS 없는 처리 지원)
2. 또는 GPS 정보를 수동으로 EXIF에 추가
3. 또는 외부 POS 파일 사용

Q: 대형 프로젝트 처리 시 메모리 부족?

A: 해결책:

1. resolution_level을 2 또는 3으로 낮춤
2. 동시 생성 출력 형식 수 감소
3. 블록 처리 사용 (다른 인터페이스 필요)

🔗 관련 링크

• 좌표계 상세 설명
• 이미지 메타데이터 설명
• 출력 형식 비교
• ReconstructAT 인터페이스 (더 많은 제어)

---

ReconstructFull은 MipMapEngine SDK 사용을 시작하는 최선의 선택입니다. 경험이 쌓이면 더 많은 제어를 위해 다른 인터페이스를 탐색할 수 있습니다.