GeOnDT for JS API

Class: UGroupBoundaryHelper

UGroupBoundaryHelper

~extends Mesh
Group의 직접 자식, Object3D 배열 또는 component 배열의 월드 위치 분포를 하나 이상의 3D 연결 buffer 경계로 표시합니다. 연결된 논리 객체 원점의 골격 주위에는 XY buffer와 height/2씩의 아래·위 범위를 적용합니다. 기본 상면과 하면은 연결 컴포넌트 전체를 포함하는 평행 평면 쌍이며, surfaceMode: 'skeleton'을 선택하면 동일한 XY 외곽과 삼각분할을 유지한 채 주변 골격의 Z 흐름을 따라가는 띠를 만듭니다. 측면은 두 면의 같은 외곽선을 연결하여 닫힌 입체를 만듭니다. V·X처럼 가지 사이가 비어 있는 대형은 전체 볼록껍질로 메우지 않고 오목한 외형을 유지합니다. 논리 객체 원점 사이의 3D 공간 거리가 connectionDistance를 넘는 위치 묶음은 독립된 입체로 분리되고 다시 연결 거리 안으로 들어오면 하나로 합쳐집니다.

new UGroupBoundaryHelper(target, options)

대상 논리 객체들의 현재 월드 위치로 최초 경계를 생성합니다. Scene 추가와 제거는 호출자가 직접 관리합니다.

Name	Type	Description
`target`	UGroupBoundaryTarget	경계를 계산할 Group, Object3D 배열 또는 component 배열
`options`	UGroupBoundaryHelperCO	생성 옵션

Example

const helper = new UGroupBoundaryHelper(aircraftGroup, {
    height: 50,
    bufferSize: 5,
    connectionDistance: 20,
    positionTolerance: 1,
    color: 0x00ffff,
    opacity: 0.2,
    renderOrder: 50,
    outline: {
        dashed: true,
        lineWidth: 2
    }
});
scene.add(helper);

// 대상 위치가 달라진 시점에 호출자가 명시적으로 갱신합니다.
helper.update();
// 상면 70, 측면 71, 하면 72, 외곽선 73으로 함께 변경합니다.
helper.setRenderOrder(70);

// Scene 수명주기와 helper 자원 수명주기를 호출자가 각각 관리합니다.
scene.remove(helper);
helper.dispose();

Members

materialMeshBasicMaterial

Methods

dispose()

helper가 소유한 상면·측면·하면·외곽선 geometry와 material을 해제합니다. Scene에서 helper를 제거하지 않으며 입력 target의 자원도 변경하지 않습니다.

getConnectionDistance()number

같은 경계 형상으로 묶을 논리 객체 원점 사이의 최대 3D 공간 거리를 반환합니다. 이 값은 bufferSize와 독립적이며 bufferSize 변경으로 함께 바뀌지 않습니다.

Returns:

Type	Description
number	현재 연결 거리

getPositionTolerance()number

객체별 지속 골격 필터의 기준 거리와 연결 간선 히스테리시스 폭을 반환합니다. 값이 클수록 위치 변화가 더 완만하게 반영되며 bufferSize와는 독립적입니다.

Returns:

Type	Description
number	현재 위치 완화 기준 거리

getRenderOrder()number

경계 본체에 적용된 현재 기준 렌더 순서를 반환합니다. 측면·하면·외곽선에는 각각 이 값보다 1·2·3 높은 순서가 적용됩니다.

Returns:

Type	Description
number	현재 기준 렌더 순서

getSurfaceMode()UGroupBoundarySurfaceMode

양의 buffer 경계에서 상면과 하면의 Z를 배치하는 방식을 반환합니다.

Returns:

Type	Description
UGroupBoundarySurfaceMode	현재 surface 배치 방식

setBufferSize(bufferSize)UGroupBoundaryHelper

연결 골격 바깥쪽의 XY buffer 거리를 변경하고 즉시 경계를 다시 계산합니다.

Name	Type	Description
`bufferSize`	number	0 이상의 buffer 거리

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setColor(color)UGroupBoundaryHelper

경계 본체 색상을 즉시 변경합니다. 외곽선 색상은 독립적으로 setOutlineStyle에서 변경합니다.

Name	Type	Description
`color`	ColorRepresentation	경계 본체 색상

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setConnectionDistance(connectionDistance)UGroupBoundaryHelper

같은 경계 형상으로 묶을 논리 객체 원점 사이의 최대 3D 공간 거리를 변경하고 즉시 경계를 다시 계산합니다. 직접 또는 연쇄적으로 연결된 원점은 같은 경계 컴포넌트로 분류됩니다.

Name	Type	Description
`connectionDistance`	number	0 이상의 3D 공간 연결 거리

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setHeight(height)UGroupBoundaryHelper

각 논리 객체 원점을 기준으로 적용할 전체 수직 높이를 변경하고 즉시 경계를 다시 계산합니다. 입력값의 절반은 원점 아래에, 나머지 절반은 원점 위에 적용됩니다.

Name	Type	Description
`height`	number	0보다 큰 전체 수직 높이

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setOpacity(opacity)UGroupBoundaryHelper

경계 본체 투명도를 즉시 변경합니다. 외곽선 투명도는 독립적으로 setOutlineStyle에서 변경합니다.

Name	Type	Description
`opacity`	number	0 이상 1 이하의 투명도

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setOutlineStyle(style)UGroupBoundaryHelper

전달된 외곽선 스타일 속성만 즉시 변경합니다. 스타일 변경은 3D 경계 geometry를 다시 계산하지 않습니다.

Name	Type	Default	Description
`style`	UGroupBoundaryHelperOutlineStyle	{}	optional 변경할 외곽선 스타일

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setPositionTolerance(positionTolerance)UGroupBoundaryHelper

위치 완화 기준을 변경하고 지속 노드·연결 이력을 새 기준으로 다시 시작합니다. 0이면 현재 위치를 즉시 사용하고, 양수이면 frame 간격을 반영한 객체별 연속 필터를 적용합니다.

Name	Type	Description
`positionTolerance`	number	0 이상의 위치 완화 기준 거리

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setRenderOrder(renderOrder)UGroupBoundaryHelper

상면의 기준 렌더 순서를 변경하고 측면·하면·외곽선에는 각각 기준값보다 1·2·3 높은 순서를 적용합니다. geometry, material과 depthTest는 변경하지 않습니다.

Name	Type	Description
`renderOrder`	number	경계 본체에 적용할 유한한 렌더 순서

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setSurfaceMode(surfaceMode)UGroupBoundaryHelper

양의 buffer 경계의 상·하면 Z 배치 방식을 변경하고 즉시 다시 계산합니다. plane은 컴포넌트 전체를 포함하는 평행 평면 쌍을 만들고, skeleton은 같은 XY 외곽을 최근접 골격의 고도에 맞춰 배치합니다.

Name	Type	Description
`surfaceMode`	UGroupBoundarySurfaceMode	새 surface 배치 방식

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

setTarget(target)UGroupBoundaryHelper

경계 계산 대상을 교체하고 즉시 새 경계를 계산합니다.

Name	Type	Description
`target`	UGroupBoundaryTarget	새 Group, Object3D 배열 또는 component 배열

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

update()UGroupBoundaryHelper

현재 대상의 논리 객체 월드 위치로 경계 geometry와 배치를 갱신합니다. 위치와 기하 옵션이 직전 성공 상태와 같으면 기존 geometry와 GPU 자원을 그대로 재사용합니다.

Throws:

현재 대상 위치로 유효한 3D 경계를 계산할 수 없는 수치 오류
Type Error

Returns:

Type	Description
UGroupBoundaryHelper	현재 helper

updateMatrixWorld(force)

부모의 현재 월드 행렬에 맞춰 helper의 정확한 로컬 행렬을 동기화한 뒤 하위 트리를 갱신합니다. 생성 후 변환된 Scene이나 Group에 추가되어도 첫 렌더 전에 월드 기준 경계 배치를 복원합니다.

Name	Type	Description
`force`	boolean	optional 강제 월드 행렬 갱신 여부

updateWorldMatrix(updateParents, updateChildren)

명시적인 월드 행렬 갱신에서도 부모 역변환을 적용하여 helper의 월드 축과 기준점을 유지합니다.

Name	Type	Description
`updateParents`	boolean	부모 행렬을 먼저 갱신할지 여부
`updateChildren`	boolean	자식 행렬까지 갱신할지 여부

Type Definitions

UGroupBoundaryHelperCOobject

UGroupBoundaryHelper 생성자 옵션입니다.

Properties:

Name	Type	Argument	Default	Description
`height`	number			각 논리 객체의 아래·위에 절반씩 확보할 전체 수직 높이
`bufferSize`	number	<optional>	5	연결 골격 바깥쪽에 적용할 XY buffer 거리
`connectionDistance`	number	<optional>	20	같은 경계 형상으로 묶을 논리 객체 원점 사이의 최대 3D 공간 거리
`positionTolerance`	number	<optional>	1	객체별 위치 필터의 기준 거리와 기존 연결 간선의 히스테리시스 폭
`surfaceMode`	UGroupBoundaryHelper.types~UGroupBoundarySurfaceMode	<optional>	'plane'	양의 buffer 경계의 상·하면 Z 배치 방식
`color`	ColorRepresentation	<optional>	0x00ffff	경계 본체 색상
`opacity`	number	<optional>	0.2	경계 본체 투명도(0~1)
`renderOrder`	number	<optional>		상면 기준 렌더 순서. 생략하면 성공한 helper 생성 순서대로 50부터 1씩 증가하고 측면·하면·외곽선에는 각각 1·2·3 높은 순서를 적용한다.
`outline`	UGroupBoundaryHelper.types~UGroupBoundaryHelperOutlineStyle \| false	<optional>		외곽선 스타일. false이면 외곽선을 숨긴다.
`name`	string	<optional>	'UGroupBoundaryHelper'	helper 객체 이름

UGroupBoundaryHelperOutlineStyleobject

경계 외곽선 스타일입니다.

Properties:

Name	Type	Argument	Default	Description
`visible`	boolean	<optional>	true	외곽선 출력 여부
`color`	ColorRepresentation	<optional>	0x00ffff	외곽선 색상
`opacity`	number	<optional>	1	외곽선 투명도(0~1)
`lineWidth`	number	<optional>	2	외곽선 굵기
`worldUnits`	boolean	<optional>	false	선 굵기의 월드 단위 사용 여부
`dashed`	boolean	<optional>	true	점선 사용 여부
`dashSize`	number	<optional>	10	점선 한 구간의 길이
`gapSize`	number	<optional>	6	점선 사이 간격

UGroupBoundaryPositionSourceobject

helper에 월드 위치를 제공하는 component 형태입니다. 일반 component와 instanced component가 공통으로 제공하는 getVectorPosition()만 요구합니다.

Properties:

Name	Type	Description
`getVectorPosition`	function	현재 3D 월드 좌표 반환 함수

UGroupBoundarySurfaceMode'plane' 'skeleton'

양의 buffer 경계에서 상면과 하면의 Z를 배치하는 방식입니다. plane은 연결 컴포넌트마다 하나의 평행 평면 쌍을 만들고, skeleton은 외곽점에서 가장 가까운 연결 골격의 고도를 따라갑니다.

UGroupBoundaryTargetGroup Array.<(Object3D|UGroupBoundaryHelper.types~UGroupBoundaryPositionSource)>

helper가 논리 객체 위치를 수집할 수 있는 대상입니다. Group 입력은 직접 자식 Object3D를 사용하고, 배열 입력은 Object3D와 component를 함께 허용합니다.