적용 버전 : 1.0.0.3.183.a

표면 체적 분석 (UAnalySurfaceVolume ) 기능 안내

관련 예제 페이지 : https://3d.geon.kr/doc/tutorial-official/analysisSurfaceVolume.html

예제에서는 분석 대상 선택, 영역 그리기, 분석 실행, 결과 확인 및 가시화 항목별 표시·숨김 기능을 확인할 수 있습니다.

적용 버전부터 해당 기능을 사용 하실 수 있습니다.

사용자가 지정한 영역의 표면을 분석하여 면적, 높이 차이, 절토량 및 성토량 등을 계산할 수 있는 표면 체적 분석 기능이 추가되었습니다.

이번 기능은 분석 계산와 결과 가시화를 분리하여, 업무 목적에 따라 필요한 계산 방식과 화면 표현을 선택적으로 구성할 수 있도록 제공됩니다.

주요 기능

1. 사용자 지정 영역 분석

지도에서 다각형 영역을 직접 그리거나 좌표를 입력하여 분석 영역을 등록할 수 있습니다.

등록된 영역은 설정한 격자 크기에 따라 분할되며, 각 격자에서 분석 대상 표면과 기준면의 높이를 비교하여 결과를 계산합니다.

2. 다양한 기준면 설정

분석 목적에 따라 다음과 같은 기준면을 사용할 수 있습니다.

• 사용자가 입력한 특정 높이 (고정 높이)
• 영역의 최저 높이 
• 지형 표면 (*지형 레이어 필수)
• 별도의 레이어 또는 3D 객체

예를 들어 높이 0m를 기준으로 계산하거나, 기존 지형과 변경된 지형을 비교하는 방식으로 활용할 수 있습니다.

3. 면적 및 체적 결과 제공

분석 완료 후 다음과 같은 결과를 확인할 수 있습니다.

• 수평 투영 면적
• 실제 계산에 사용된 유효 면적
• 표면 면적
• 영역 둘레
• 절토 / 성토량
• 순 체적
• 최소·최대·평균 높이 차이
• 전체 격자 및 유효 격자 수
• 분석 영역의 유효 샘플 비율

분석 결과에 대한 정밀도는 격자의 크기가 커질수록 낮아지므로 참고 하시기 바랍니다.

4. 분석 결과 가시화

분석 결과는 필요한 항목만 선택하여 화면에 표시할 수 있습니다.

• 분석 영역 외곽선
• 분석 격자
• 높이 차이 Heatmap
• 현재 표면과 기준면 사이의 수직선
• 분석 결과 라벨
• 사용자 정의 3D 가시화 객체 

각 가시화 항목은 개별적으로 추가, 표시, 숨김, 수정 및 제거할 수 있습니다.

따라서 분석 결과 값만 사용하거나, 필요한 가시화 항목만 선택하여 업무 화면에 적용할 수 있습니다.

기본 사용 절차

1. 분석 객체 가져오기

U3dApp.getAnalysis('SurfaceVolume') : 표면 체적 분석 클래스를 반환해줍니다.

2. 분석 대상 설정

analy.setTarget(targetOption) :  분석 대상은 레이어 또는 개별 3D 객체로 설정할 수 있습니다.

레이어를 대상으로 설정

 - 레이어 타입 지정시 layerName 으로 대상 레이어 이름 설정

3D 객체를 대상으로 설정

target type 설명

targetOption 정보

3. 기준면 설정

기준면은 체적 계산 시 대상 표면과 비교되는 기준입니다.

analy.setReferenceSurface(referenceOption) : 기준면의 대상을 설정합니다.

고정 고도 기준면 (type : constant-height)

 - 고정 고도 기준면의 경우 height를 설정하여 해당 면의 높이값을 설정합니다. (m 기준)

지형 기준면 (type : terrain)

레이어 기준면  (type : layer)

3D 객체 기준면  (type : object3d)

referenceOption 정보

referenceSurface type 설명

4. 분석 옵션 설정

analy.setAnalysisOption(analyOption) : 분석에 대한 해상도 및 격자 최대수량 등을 조절 할수 있습니다.

 분석 실행시에 설정하는 옵션 값입니다.

격자의 해상도 조절, helper의 가시화 제어 등을 설정 할수 있습니다. 

analyOption 정보

5. 분석 영역 등록

analy.addVolumeArea(SurfaceVolumeAreaOption) : 분석 대상 영역을 등록합니다.

그리기로 영역을 입력하거나, 좌표 배열을 직접 전달하여 분석 영역을 등록합니다.

SurfaceVolumeAreaOption 정보 

6. 분석 실행

analy.runAnalysis(area.getId()) : 추가 한 분석 영역에 대해서 분석을 실행하여 결과를 반환받습니다. 

결과는 비동기로 작업하여 반환합니다.

runAnalysis()는 등록된 분석 영역을 대상으로 다음 작업을 순서대로 수행합니다.

1. 분석 영역의 격자 및 표면 샘플 준비
2. 체적 계산 실행
3. 계산 결과 유효성 검증
4. 분석 영역에 결과 등록
5. 완료 이벤트 및 결과 반환

7. 분석 결과 확인

면적 결과

area에는 분석 영역의 면적과 둘레 정보가 포함됩니다.

투영 면적과 유효 면적의 차이

area.projected는 입력한 전체 Polygon을 기준으로 계산됩니다.

반면 area.effective는 분석 대상 또는 기준면의 샘플을 정상적으로 얻은 셀만을 기준으로 계산됩니다.

따라서 일부 영역에서 표면을 찾지 못한 경우 두 값이 서로 다를 수 있습니다.

체적 결과

volume에는 기준면을 기준으로 계산된 절토량과 성토량이 포함됩니다.

높이 결과

height에는 현재 표면과 기준면 사이의 높이 차이 통계가 포함됩니다.

양수는 일반적으로 현재 표면이 기준면보다 높은 상태를 의미하며, 음수는 현재 표면이 기준면보다 낮은 상태를 의미합니다.

Sampling 결과

sampling에는 샘플링하여 나온 결과에 대한 정보를 담고 있습니다.

셀별 상세 결과

cells에는 분석 격자별 상세 계산 결과가 포함됩니다.

셀 결과는 다음 기능에서 사용됩니다.

• 높이 차이 Heatmap 생성
• 절토·성토 수직선 생성
• 셀별 상세 결과 표시
• 사용자 정의 분석 가시화
• 개별 셀 결과 조회

8. 가시화 항목 추가

분석 완료 후 외곽선, 격자, Heatmap, 수직선 등을 추가할 수 있습니다.

외곽선 Helper

analy.addBoundary(opt) : 외곽선 helper를 추가합니다.

- 외곽선 helper 형상

격자 helper

analy.addGrid(opt) : 격자 helper를 추가합니다.

 - 격자 helper 형상

Heatmap Helper

analy.addHeatmap(opt) : heatmap helper를 추가합니다.

 - heatmap helper 형상

수직선 Helper

analy.addVerticalLines(opt) : 수직선 helper를 추가합니다.

 - 수직선 helper 형상

opt 정보

9. 분석 이벤트 및 로딩 처리

분석 진행 상태는 이벤트를 통해 확인할 수 있습니다.

주요 이벤트는 다음과 같습니다.

주의 사항

분석 해상도 설정

분석의 정밀도는 resolution 값을 통해 설정할 수 있습니다.

값을 작게 설정할수록 더 촘촘한 격자로 분석되어 세부적인 결과를 얻을 수 있지만, 생성되는 격자 수와 분석 시간이 증가합니다.

대규모 영역을 지나치게 작은 해상도로 분석하면 설정된 최대 격자 수를 초과할 수 있으므로, 분석 영역의 크기와 필요한 정밀도를 고려하여 적절한 값을 설정해야 합니다.

분석 진행 중 화면 처리

분석을 수행하는 동안에는 사용자가 지도나 3D 화면을 조작하지 않도록 업무 화면에서 로딩 화면을 표시하는 것을 권장합니다.

분석 완료, 오류 또는 취소 시에는 로딩 화면이 정상적으로 종료되도록 처리해야 합니다.

해당 입력 차단 및 로딩 화면 처리는 분석 엔진 내부가 아닌 적용 화면에서 관리합니다.

사용 시 주의사항

• Heatmap과 수직선은 분석이 완료되고 격자별 결과가 생성된 이후 사용할 수 있습니다.

• 분석 영역이나 격자 크기, 기준면이 변경되면 기존 분석 결과와 가시화 항목이 제거되고 다시 분석됩니다.
• 동일한 ID의 가시화 항목을 중복으로 추가할 수 없습니다. 기존 항목을 교체하려면 replace 옵션을 사용해야 합니다.
• 사용자 계산 결과는 필수 데이터 구조와 숫자 형식만 검증됩니다.
• 절토·성토 계산 공식, 보간 방법, 누락된 샘플 처리 기준 등 업무 계산의 정확성은 적용하는 사용자 계산 함수에서 별도로 검증해야 합니다.
• 사용자 계산 함수에서 분석 취소 상태를 확인하도록 구현하면 취소 요청에 더 빠르게 반응할 수 있습니다.
• 분석 결과를 복원한 후 다시 계산하는 경우, 저장 당시 사용한 계산기 ID가 사전에 등록되어 있어야 합니다.