Class: UFrustumTerrainProjectionHelper

const helper = new UFrustumTerrainProjectionHelper(frustum, {
    color: 0x00ffff,
    lineWidth: 3,
    opacity: 0.6
});
scene.add(helper);

Methods

dispose()

helper가 생성한 geometry, material, 투영선, cache를 해제하는 메서드입니다.

getEffectiveTerrainStampGridSize()number

마지막 terrain footprint 생성에서 실제 출력 topology에 사용한 격자 크기를 반환한다. 보통 요청값과 같고, 128 polygon 예산을 넘는 복잡한 패턴에서만 더 작은 값이 된다.

Returns:

Type	Description
number

getFillColor()Color|string|number|undefined

Returns:

Type	Description
Color | string | number | undefined

getFillOpacity()number|undefined

Returns:

Type	Description
number | undefined

getGradientColor()Color|string|number|undefined

terrain stamp fill의 그라데이션 두 번째 색상을 반환한다.

Returns:

Type	Description
Color | string | number | undefined

getGradientDirection()'vertical'|'horizontal'|undefined

terrain stamp fill의 그라데이션 방향을 반환한다.

Returns:

Type	Description
'vertical' | 'horizontal' | undefined

getIntersectionSteps()number

현재 near -> far 지면 교차 분할 수를 반환한다.

Returns:

Type	Description
number

getSideColor()Color|string|number|undefined

Returns:

Type	Description
Color | string | number | undefined

getSideOpacity()number|undefined

Returns:

Type	Description
number | undefined

getTemporalFarSmoothingFactor()number

현재 far 회전 적응형 시간 보정 강도를 반환한다.

Returns:

Type	Description
number

getTemporalHalfLifeMs()number

현재 시간 필터 기본 반감기(ms)를 반환한다.

Returns:

Type	Description
number

getTemporalHysteresisDistance()number

현재 far 코너 히스테리시스 거리(m)를 반환한다.

Returns:

Type	Description
number

getTemporalSnapGapMs()number

현재 시간 안정화 update 단절 기준(ms)을 반환한다.

Returns:

Type	Description
number

getTemporalStabilization()boolean

현재 자세 시간 안정화 사용 여부를 반환한다.

Returns:

Type	Description
boolean

getTerrainBoundaryRefinementSteps()number

현재 footprint 경계 이분 정제 횟수를 반환한다.

Returns:

Type	Description
number

getTerrainIntersectionHalfLifeMs()number

현재 지면 광선 결과 시간 평균 반감기(ms)를 반환한다.

Returns:

Type	Description
number

getTerrainIntersectionHitPersistenceMs()number

현재 지면 hit/miss 상태 확인 시간(ms)을 반환한다.

Returns:

Type	Description
number

getTerrainIntersectionMaxLagDistance()number

현재 지면 교차 결과의 경계/광선 방향별 한 번 보정 목표 제한 거리(m)를 반환한다.

Returns:

Type	Description
number

getTerrainIntersectionMedianWindow()number

현재 지면 광선 교차 중앙값 표본 개수를 반환한다.

Returns:

Type	Description
number

getTerrainIntersectionStabilization()boolean

현재 지면 광선 결과 안정화 사용 여부를 반환한다.

Returns:

Type	Description
boolean

getTerrainStampGridSize()number

현재 footprint UV 격자의 한 변 샘플 수를 반환한다.

Returns:

Type	Description
number

getUpdateIntervalMs()number

현재 Helper 자체 갱신 목표 주기(ms)를 반환한다.

Returns:

Type	Description
number

getVisible()boolean

setVisible()로 설정한 helper 전체 표시 상태를 반환한다.

Returns:

Type	Description
boolean

resetTerrainIntersectionStabilization()UFrustumTerrainProjectionHelper

누적된 지면 광선·경계 이력을 버리고 다음 update를 현재 결과에서 다시 시작한다. 카메라 정보나 지형 데이터 세트를 서비스 코드에서 교체한 직후 수동으로 호출할 수 있다.

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setColor(color)UFrustumTerrainProjectionHelper

helper 선 색상을 변경하는 메서드입니다.

Name	Type	Description
color	Color | string | number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setFillColor(color)UFrustumTerrainProjectionHelper

plane fill(비-terrain far plane mesh, terrain stamp) 색상을 변경한다. terrain stamp는 update() 시 fillOptions를 다시 읽어 반영된다.

Name	Type	Description
color	Color | string | number | undefined

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setFillOpacity(opacity)UFrustumTerrainProjectionHelper

plane fill(비-terrain far plane mesh, terrain stamp) 투명도를 변경한다.

Name	Type	Description
opacity	number | undefined

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setFrustum(frustum)UFrustumTerrainProjectionHelper

프러스텀 객체를 교체하고 현재 평면 정보로 helper geometry를 다시 만든다.

Name	Type	Description
frustum	Frustum

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setGradientColor(color)UFrustumTerrainProjectionHelper

terrain stamp fill의 그라데이션 두 번째 색상을 변경한다. texture 옵션이 있으면 shader에서는 texture가 우선되어 gradient가 적용되지 않는다.

Name	Type	Description
color	Color | string | number | undefined

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setGradientDirection(direction)UFrustumTerrainProjectionHelper

terrain stamp fill의 그라데이션 방향을 변경한다.

Name	Type	Description
direction	'vertical' | 'horizontal'

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setIntersectionSteps(intersectionSteps)UFrustumTerrainProjectionHelper

near -> far 광선의 지면 교차 탐색 분할 수를 변경한다. 2~64 정수로 제한하며, 값이 커질수록 깊이 방향의 최초 접점은 정밀해지지만 한 번의 지형 높이 조회량도 선형으로 증가한다.

Name	Type	Description
intersectionSteps	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setLineWidth(lineWidth)UFrustumTerrainProjectionHelper

helper 선 두께를 변경하는 메서드입니다. 유한한 양수가 아닌 값은 무시하고 마지막 정상 두께를 유지합니다.

Name	Type	Description
lineWidth	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setOpacity(opacity)UFrustumTerrainProjectionHelper

helper 선 투명도를 변경하는 메서드입니다.

Name	Type	Description
opacity	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setSideColor(color)UFrustumTerrainProjectionHelper

프러스텀 옆면 fill 색상을 변경한다. side mesh가 아직 없고 fill이 enabled면 이 시점에 생성해서 붙인다. color와 opacity가 모두 undefined가 되면 side mesh를 제거한다.

Name	Type	Description
color	Color | string | number | undefined

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setSideOpacity(opacity)UFrustumTerrainProjectionHelper

프러스텀 옆면 fill 투명도를 변경한다. side mesh가 아직 없고 fill이 enabled면 이 시점에 생성해서 붙인다. color와 opacity가 모두 undefined가 되면 side mesh를 제거한다.

Name	Type	Description
opacity	number | undefined

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTemporalFarSmoothingFactor(temporalFarSmoothingFactor)UFrustumTerrainProjectionHelper

far 코너 오차에 따라 기본 반감기를 추가로 늘리는 보정 강도를 변경한다. 0~4 범위이며, 0은 추가 보정 없음이고 값이 클수록 긴 far 면이 자연스럽게 변하지만 현재 자세와의 시각적 지연도 커진다.

Name	Type	Description
temporalFarSmoothingFactor	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTemporalHalfLifeMs(temporalHalfLifeMs)UFrustumTerrainProjectionHelper

시간 필터의 기본 반감기(ms)를 변경한다. 큰 값은 더 부드럽지만 원시 프러스텀을 늦게 추종하고, 작은 값은 정확하게 따라가지만 떨림이 더 드러난다. 유한한 양수만 사용하며, 잘못된 값은 현재 정상 반감기를 유지한다.

Name	Type	Description
temporalHalfLifeMs	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTemporalHysteresisDistance(temporalHysteresisDistance)UFrustumTerrainProjectionHelper

far 코너의 작은 왕복 변화를 무시할 world 거리(m)를 변경한다. 현재 자세 이력은 보존하되 hold 상태만 해제해 다음 update에서 새 임계값으로 다시 판정한다. 유한한 0 이상의 값을 사용하며, 잘못된 값은 현재 정상 거리를 유지한다.

Name	Type	Description
temporalHysteresisDistance	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTemporalSnapGapMs(temporalSnapGapMs)UFrustumTerrainProjectionHelper

시간 안정화 이력을 즉시 현재 자세로 전환할 update 단절 기준(ms)을 변경한다. 저주기 서비스에서는 호출 간격보다 크게 설정해야 반감기와 far 보정이 계속 적용된다.

Name	Type	Description
temporalSnapGapMs	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTemporalStabilization(temporalStabilization)UFrustumTerrainProjectionHelper

Helper 고정 tick 사이의 자세 시간 안정화 사용 여부를 변경한다. 전환 시 과거 자세를 버려, 다시 켰을 때 오래된 형상에서 현재 위치까지 따라오는 잔상을 막는다.

Name	Type	Description
temporalStabilization	boolean

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTerrainBoundaryRefinementSteps(terrainBoundaryRefinementSteps)UFrustumTerrainProjectionHelper

hit/miss로 검출된 footprint 경계를 이분 정제할 횟수를 변경한다. 0~12 정수로 제한한다. 격자나 stamp 수를 늘리지 않고 경계 구간만 좁히므로, 큰 far에서도 128 stamp 제한을 유지하며 정밀도를 높일 수 있다.

Name	Type	Description
terrainBoundaryRefinementSteps	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTerrainIntersectionHalfLifeMs(terrainIntersectionHalfLifeMs)UFrustumTerrainProjectionHelper

지면 광선 교차 거리와 정제 경계 위치의 시간 평균 반감기(ms)를 변경한다. 0~60000 범위이며 0이면 중앙값 결과를 즉시 사용하고, 값이 클수록 진폭은 줄지만 지면 경계 추종이 늦어진다. 20ms 이상은 실제 경계를 따라가는 동안 형상이 늘어져 보일 수 있어 권장하지 않는다.

Name	Type	Description
terrainIntersectionHalfLifeMs	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTerrainIntersectionHitPersistenceMs(terrainIntersectionHitPersistenceMs)UFrustumTerrainProjectionHelper

지면 ray의 hit/miss가 반대로 바뀐 뒤 새 상태로 확정하기까지 유지할 시간(ms)을 변경한다. 0~60000 범위이며 0이면 즉시 전환하고, 값이 클수록 한두 번의 판정 요동은 줄지만 새 영역 출현·소멸이 늦어진다.

Name	Type	Description
terrainIntersectionHitPersistenceMs	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTerrainIntersectionMaxLagDistance(terrainIntersectionMaxLagDistance)UFrustumTerrainProjectionHelper

최근 측정의 중앙값 목표가 크게 바뀔 때 경계 방향과 광선 깊이 방향에서 한 번의 필터 계산에 허용할 최대 world 거리(m)를 변경한다. 제한된 목표에는 지면 결과 반감기 EMA가 다시 적용되므로 실제 3차원 표시점의 이동량 상한은 아니다. 작은 값은 큰 진폭을 더 강하게 나눠 반영하지만 실제 변화 추종이 느리고, 큰 값은 더 빠르게 추종한다. 30m보다 큰 값은 보정한 지면점이 현재 camera ray에서 유효한지 검사하는 재투영 허용거리에도 사용된다. 0이면 접촉 위치의 거리·시간·중앙값 보정만 건너뛰며 hit/miss 변경 확인 시간은 계속 적용된다.

Name	Type	Description
terrainIntersectionMaxLagDistance	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTerrainIntersectionMedianWindow(terrainIntersectionMedianWindow)UFrustumTerrainProjectionHelper

고정 UV ray별 최근 교차 거리에서 순간 튐을 제거할 중앙값 표본 개수를 변경한다. 1~31의 홀수로 정규화하며, 1은 이력 없이 현재 결과만 사용한다.

Name	Type	Description
terrainIntersectionMedianWindow	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTerrainIntersectionStabilization(terrainIntersectionStabilization)UFrustumTerrainProjectionHelper

지면 광선 결과의 프레임 간 안정화 사용 여부를 변경한다. 자세 시간 보정과 독립된 기능이며, 끄면 다음 update부터 현재 광선 결과를 그대로 사용한다.

Name	Type	Description
terrainIntersectionStabilization	boolean

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setTerrainStampGridSize(terrainStampGridSize)UFrustumTerrainProjectionHelper

far plane footprint를 분류할 정규 UV 격자의 한 변 샘플 수를 변경한다. 3~17의 홀수로 정규화하며, 값이 클수록 far 면의 작은 지형 변화와 경계를 더 촘촘히 검출한다. topology가 UTerrainStamp 128개 예산을 넘는 극단적 패턴은 이미 조회한 ray의 부분 집합으로 안전하게 낮춰 출력한다.

Name	Type	Description
terrainStampGridSize	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setUpdateIntervalMs(updateIntervalMs)UFrustumTerrainProjectionHelper

렌더 중 현재 Frustum 상태를 다시 읽을 고정 목표 주기(ms)를 변경한다. Helper는 이 값과 관계없이 Frustum의 상태 변경 API를 호출하지 않는다. 1ms 이상의 유한한 양수만 사용하며, 잘못된 값은 현재 정상 주기를 유지한다. 브라우저 timer 지연이나 지형 계산 시간이 길면 실제 주기는 설정값보다 늦어질 수 있으며, 놓친 tick은 연속 실행하지 않고 다음 주기부터 다시 계산한다.

Name	Type	Description
updateIntervalMs	number

Returns:

Type	Description
UFrustumTerrainProjectionHelper

setVisible(visible)UFrustumTerrainProjectionHelper

helper 전체 표시 상태를 변경한다. false이면 외곽선, side/fill mesh, projection line, terrain stamp fill/mask를 모두 끈다.

Name	Type	Description
visible	boolean

Returns:

Type	Description
UFrustumTerrainProjectionHelper

update()UFrustumTerrainProjectionHelper

현재 프러스텀 평면으로 외곽선을 갱신하는 메서드입니다.

Returns:

Type	Description
UFrustumTerrainProjectionHelper

updateMatrixWorld(force)

마지막 고정 주기 update에서 확정한 matrix로 LineSegments2의 world matrix를 갱신한다. renderer 경로에서 원시 Frustum matrix를 다시 읽으면 line/side만 먼저 움직이고 world 좌표인 terrain stamp는 다음 tick까지 남아 서로 어긋나므로 여기서는 확정 matrix를 그대로 유지한다.

Name	Type	Description
force	boolean	optional