생태원 기후대응 사업 구현 목표 서비스와 관련된 GeOnDT for JS 기능에 대한 상세 안내 드립니다.

볼드체로 표현된 함수이름 이나 소스 구문은 관련 예제에서 검색하여 사용법과 구문 흐름을 파악해 봐야한다는 의미입니다.

대규모 컴포넌트(U3dLodModelLayer) – typeLodTable(lods) 기반 생성/LOD 설정 가이드

이 문서는 feature 속성값(type) 에 따라 모델을 매핑하고, 카메라 거리(distance) 에 따라 LOD 모델을 자동 전환하는 [ U3dLodModelLayer ]생성 방법을 안내합니다.

• 이 가이드에서 볼드 처리된 함수/옵션명은 예제 코드에서 검색하여 전체 흐름을 함께 파악해야 하는 항목입니다.
• 예제는 [tutorial-official/hugeVolumeComponent.html]의 [initComponentLayer()]설정을 기준으로 설명합니다.

참고 예제

• 대용량/대규모 컴포넌트 예제(본 가이드 기준 예제)
  • https://3d.geon.kr/doc/tutorial-official/hugeVolumeComponent.html

1. 개요

U3dLodModelLayer 는 다음을 한 번에 처리하는 모델 레이어입니다.

현재의 예제는 사전에 준비된 Lod 모델 데이터를 기반으로 작성 되었습니다. 

데이터를 준비 후 사용을 권장드립니다.

• (1) 서버(Geoserver)에서 feature 데이터를 타일 단위로 로드
• (2) feature 속성값(type)에 따라 모델 선택
• (3) 카메라 거리(distance)에 따라 LOD 모델 자동 전환
• (4) 매우 많은 객체를 Instanced Mesh 방식으로 렌더링

이때 핵심 설정은 다음 2가지입니다.

• typeColName: feature 속성 중 “타입 구분에 사용할 key” (예제에서 설정된 값 : 'smpvm_cd')
• typeLodTable: “타입 값(type) → 거리별 모델명(lods)” 테이블

2. 레이어 생성 옵션 설명 

2.1. 기본 옵션(예제 기준)

[initComponentLayer()]의 예제 옵션은 다음 흐름입니다.

• 레이어 기본:
  • name, type, listmodel, needxml, drawline
• 데이터 소스(피처 로딩):
  • layername, baseurl, ext
• 타일 레벨:
  • minlevel, maxlevel
• 타입/LOD 매핑(핵심):
  • typeColName *필수
  • typeLodTable *필수
• 스타일/필터:
  • [styleFunction] 색상 및 가시화에 대한 스타일 설정 함수
    -> (대상이 생성된 이후에 호출 됩니다.)
  • [pointsFilterFunction] feature정보를 불러와 생성된 점 좌표에 대한 정보를 반환 합니다.
    -> 해당 구문을 통해 위치, 크기, 회전 값을 설정 할 수 있습니다. ( 높이값 포함 )

2.2. typeColName (필수)

typeColName: STYLE_INFO.COLNAME // 예: "smpvm_cd"

• geoserver 서버에서 받은 feature의 feature.properties[typeColName] 값을 읽어서
• 어떤 모델을 선택할지 결정합니다.

예:

• feature.properties["smpvm_cd"] === "2" 이면 “산길나무” 타입으로 보고
• typeLodTable에서 type: "2" 행을 찾아 LOD 규칙을 적용합니다.

2.3. typeLodTable (필수) – 타입별 거리 LOD 테이블

예제에서 사용한 포맷:

typeLodTable: [
  {
    type: '1',
    lods: { 50:'tree_base', 200:'tree_middle', 20000:'tree_low' }
  },
  {
    type: '2',
    lods: { 50:'mongolian_oak_base', 200:'mongolian_oak_middle', 20000:'mongolian_oak_low' }
  },
  ...
  {
    type: 'default',
     lods: { 50: 'pine_base', 200: 'pine_middle', 20000: 'pine_low' }
  }
]

type 의미

• type: 피처 속성값(문자열로 비교)
• 권장: 실제 피처의 속성값이 숫자여도 문자열로 작성 ('1', '2' …)
• type: 'default'는 매칭되는 타입이 없을 때의 기본 규칙으로 사용(프로젝트 정책에 따라 사용)

lods 의미

• lods: “거리(distance) → 모델명(modelName)” 맵
• LOD 개수 제한 없음 (3단계 고정이 아니라, 사용자가 원하는 만큼 추가 가능)

지원하는 lods 형식(둘 다 가능):

• 객체 형태
  • { 50:'A', 200:'B', 20000:'C' }
• 배열 형태
  • [[50,'A'], [200,'B'], [20000,'C']]
  • 또는 [{distance:50, model:'A'}, ...] 형태도 지원

3. listmodel 작성 규칙 (중요)

typeLodTable.lods 안에 들어가는 “모델명”은 반드시 listmodel의 name과 일치해야 합니다.

예:

const LIST_MODEL = [
  { name: 'mongolian_oak_base', baseurl: '...', fileName:'...', ext:'3ds', ... },
  { name: 'mongolian_oak_middle', ... },
  { name: 'mongolian_oak_low', ... },
]

• typeLodTable.lods에 'mongolian_oak_middle'을 적었다면
• LIST_MODEL에도 name: 'mongolian_oak_middle' 항목이 존재해야 정상 로드됩니다.

4. 레이어 생성 코드 예시

[ https://3d.geon.kr/doc/tutorial-official/hugeVolumeComponent.html - initComponentLayer()] 레이어 생성 옵션 부분을 참고해주세요.

5. 가변 LOD 구성 예시 (LOD 단계가 3개를 넘는 경우)

아래처럼 distance 단계가 많아도 그대로 작성 가능합니다.

• 생성 방식에 따라 LOD 단계를 늘려서 생성 가능합니다.

6. 속성값으로 검색된 객체에 대한 스타일 설정

속성값으로 검색된 객체에 대한 스타일 설정이 가능합니다. 

해당 객체에 대해서 전체 적용 또는 다중으로 적용되므로 참고 하기시 바랍니다.

 [ 예제 - UI 기능 버튼 중 ]

해당 예제의 UI에서 확인 가능하며 

applyStyleToInstances() 해당 부분을 참고하십시오.

예제 코드 ( https://3d.geon.kr/doc/tutorial-official/hugeVolumeComponent.html - applyStyleToInstances() 부분) 

•  U3dLodModelLayer.getMeshByPropertiesMap(propertyKey, value) :  feature의 속성값 또는 함수를 설정하여 해당하는 해당하는 결과를 반환합니다.
  • 반환 결과 {mesh, idxList} : mesh - 대상 instancedMesh 객체 / idxList - 검색된 대상의 index 목록
•  U3dLodModelLayer.setColorByList(meshList, color, opacity, excludeTexture) : {mesh, idxList} 형태의 object 형식과 color, opacity를 입력 받아 스타일을 변경합니다. 
  • excludeTexture : 색상 적용시 텍스쳐을 제외하고 반영 할 지에 대한 여부 (boolean) - 기본값 false
•  U3dLodModelLayer.setScaleByList(meshList, scale) : {mesh, idxList} 형태의 object 형식과 scale (수치 또는 THREE.Vector3 )을 입력받아 크기를 변경합니다.
•  U3dLodModelLayer.setVisibleByList(meshList, visible) : {mesh, idxList} 형태의 object 형식과 visible(boolean) 를 입력 받아 가시화를 변경합니다. 
• styleFunction 이 설정 됐을 경우에 위에 해당하는 설정은 미적용됩니다. [ styleFunction 은 tile update 후에 객체 생성 후 마지막에 호출됩니다. ]

7. 가시화 이미지 예시

[색상 적용 (텍스쳐 포함 : excludeTexture - false)]  *텍스쳐가 존재하는 모델의 경우 색상이 혼합 적용되어 반영되므로 참고하시기 바랍니다.

[색상 적용 (텍스쳐 미포함 : excludeTexture - true)]

8. WFS Paging(페이징) 관련 옵션

U3dLodModelLayer는 내부적으로 WFS GetFeature 요청 시, 상황에 따라 URL에 maxFeatures, startIndex를 붙여 여러 페이지를 순회 로딩할 수 있습니다.

레이어 생성시 WFS Paging 속성값 추가

아래의 3개의 속성은 WFS Paging 관련 속성입니다.

• wfsUsePaging[boolean]
• wfsMaxFeatures[number]
• wfsPagingMaxPages[number]

wfsUsePaging (기본값: true)

• 설명 
  • true이면 WFS 요청을 여러 번 호출하면서 startIndex를 증가시켜 페이지 단위로 계속 가져옵니다.
  • false이면 페이징 파라미터(maxFeatures, startIndex)를 붙이지 않고 1회 요청으로 끝냅니다.
• 주의 
  • usePaging=false는 서버 기본 동작에 따라
    • 결과가 “일부만” 오거나(서버 default limit)
    • 반대로 “너무 많이” 내려와서 네트워크/메모리 부담이 커질 수 있습니다.
  • 대용량 포인트(WFS)라면 일반적으로 true 권장입니다.

wfsMaxFeatures (기본값: 500)

• 설명 
  • 페이지 1회 요청에서 받아올 feature 개수.
  • 값이 유효한 양수이고(> 0) + usePaging=true일 때만 실제 URL에 &maxFeatures=...로 반영됩니다.
• 튜닝 가이드 
  • 값이 너무 크면:
    • 한 번에 파싱/생성 비용이 커져 프레임 드랍 가능
  • 값이 너무 작으면:
    • 요청 횟수가 많아져 네트워크 오버헤드 증가

wfsPagingMaxPages (기본값: 5000)

• 설명 
  • 타일 1개에 대해 페이징을 몇 페이지까지 허용할지의 “안전 장치”입니다.
  • 내부에서 최소 1 이상으로 보정됩니다.

9. Sampling(샘플링) 관련 옵션

Sampling은 “표시/생성 비용이 큰 구간에서” 데이터를 일부만 먼저 보여주고(또는 일부만 사용) 성능을 확보하기 위한 옵션입니다.
U3dLodModelLayer는 타일 레벨이 특정 기준 이하일 때만 sampling을 고려합니다.

samplingStartLevel (정적 기준, 기본값: 17)

• 설명 
  • 타일 레벨이 samplingStartLevel 이하일 때만 sampling을 적용 대상으로 판단합니다.
  • 기본값은 U3dLodModelLayer.samplingStartLevel = 17 입니다.
• 설정 방법 
  • 레이어 생성 후 U3dLodModelLayer.setSamplingStartLevel(level)로 변경할 수 있습니다.

의미: 예를 들어 samplingStartLevel = 17 이면
level <= 17 구간에서만 sampling 로직을 사용하고, 그보다 큰 레벨(더 상세/근접)에서는 sampling을 끄는 방식으로 운용할 수 있습니다.

sampling 옵션 형태

Sampling은 타일에서 생성되는 전체 feature 중 일부만 선택적으로 가시화하여 성능을 최적화하기 위한 기능입니다.

설정한 비율만큼만 데이터를 표시합니다.

1) sampling: { enabled, pointRate, minPointsPerFeature, seed, progressive } (권장)

• enabled (boolean)
  Sampling 기능 사용 여부
  • true일 때만 동작
• pointRate (number, 0 ~ 1 / 기본값: 0.1)
  전체 feature 중 표시할 비율
  •  예: 0.1 = 10%만 표시
  • 1 이상이면 Sampling이 무의미하므로 내부적으로 비활성 처리됨
• minPointsPerFeature (number, 정수 / 기본값: 0)
  각 feature당 최소로 보장되는 point 개수
  • Sampling 비율과 관계없이 이 값은 반드시 유지됨 (*현재의 예제는 point type으로 최소 1개는 생성되므로 1개보다 작은값으로 설정됨)
• seed (string / 기본값: 'v1')
  랜덤 Sampling 결과를 고정하기 위한 시드 값
  • 동일한 seed 사용 시 항상 동일한 Sampling 결과 보장
• progressive (boolean)
  점진적 렌더링 여부
  • true일 경우, WFS Paging 사용 시 첫 페이지 로드 완료 후 즉시 렌더링 시작
  • 이후 페이지가 로드될 때마다 데이터를 추가로 생성 및 표시

Progressive Sampling 사용 조건 (중요)

progressive 옵션은 WFS 페이징이 활성화된 경우에만 의미가 있습니다.
단순히 progressive: true만 설정한다고 동작하지 않습니다.

활성화 조건

아래 조건을 모두 만족해야 progressive sampling이 실제로 동작합니다:

• wfsUsePaging === true

• wfsMaxFeatures가 유효한 양수

• sampling.enabled === true

• sampling.progressive === true

• sampling.pointRate < 1

핵심 정리

• progressive는 페이징 기반 점진적 렌더링 기능

• 페이징이 없으면 동작하지 않음

• Sampling이 비활성화 상태이거나 (enabled: false)

• pointRate >= 1이면 의미 없음

옵션 예시(가이드용)

• WFS 페이징 + progressive sampling 조합 예시로는 아래 같은 형태를 권장합니다.

• samplingStartLevel: 필요 시 U3dLodMO.setSamplingStartLevel(level) 조정

U3dLodModelLayer 생성시  WFS 페이징, sampling 속성 ( 권장 값 ) -  환경에 따라 수치 조절가능

 *아래의 권장값으로 기본설정 되어있습니다.

10. 주의사항

• (1) lods에 적은 모델명이 LIST_MODEL.name에 없으면 해당 LOD 단계에서 모델이 로드되지 않습니다.
• (2) distance key는 숫자여야 합니다. ("200"도 내부에서 Number 변환되지만, 권장: 숫자/숫자문자열 혼용 금지)
• (3) typeColName은 feature에 실제 존재하는 속성명이어야 합니다.
• (4) type 값은 문자열 비교를 하므로 type: 2 보다 type:'2' 형태를 권장합니다.
• (5) feature의 point type만 반영하여 적용하였습니다.