GeOnDT GeOnDT for JS

Class: U3dPathGeometry

U3dPathGeometry

~extends U3dGeometry
여러 좌표를 부드러운 곡선으로 이어, 폭과 높이를 가진 띠(리본) 형태로 세운 경로·항로 도형입니다.
두 가지 방법으로 만드실 수 있습니다.

  • 마우스로 직접 그리기: `draw()`로 그리기 모드를 켠 뒤 화면을 클릭해 점을 추가하고, 더블클릭(또는 `endPathPoint()`)으로 완성합니다.
  • 좌표로 바로 생성: 월드 좌표 목록을 준비해 `createPathMesh(vertices, opt)`로 한 번에 만듭니다.
생성 후에는 `modify()`로 편집점을 드래그해 경로를 수정하거나, `export()`/`import()`로 경로를 저장·복원하실 수 있습니다.

new U3dPathGeometry(options)

경로(항로) 도형을 생성합니다.
생성만으로는 화면에 나타나지 않습니다. 이후 draw()로 마우스로 그리거나, createPathMesh()/updateByPoints()로 좌표를 넣어 경로를 만들어 주세요.

Name Type Default Description
options U3dPathGeometryCO {} optional

생성 옵션 (색상·두께·좌표·편집 옵션 등)

Members

renderOrdernumber

그리는 순서입니다.
값이 큰 객체를 나중에 그려 앞쪽에 보이게 합니다. 경로는 UDEF.RENDER_ORDER.USER 값으로 만들어집니다.

Methods

addPoint(point)

경로에 새 점을 추가하고 경로를 다시 그립니다.
마우스 이벤트를 넘기면 클릭 지점을, 좌표를 넘기면 그 위치를 점으로 추가합니다.

Name Type Description
point U3dMouseEvent | Vector3 | Vector3Like

마우스 이벤트 또는 추가할 점 좌표

Example
let path = new Union3D.geom.U3dPathGeometry();
path.draw();
let pos = new THREE.Vector3(100,100,0);
path.addPoint(pos);

addPointInPath(point, color, setName)Object|undefined

경로 위의 한 지점에 편집점과 구체를 추가합니다.
추가된 점은 Gizmo 로 드래그하거나 위치를 옮겨 경로 중간을 편집할 수 있습니다.

Name Type Description
point WorldPositionVector3

추가하려는 항로 위의 점 위치 (월드 좌표, EPSG:3857)

color ColorRepresentation

생성되는 구체의 색상

setName string

생성되는 구체의 이름

Returns:
Type Description
Object | undefined 항로 curve 좌표 목록의 index 번호와 좌표
Example
const intersect = app.intersectAtPixel(e, false, true);
const position = intersect[0].point; // 마우스 클릭 이벤트로 월드 좌표 얻기
const objInfo = path.addPointInPath(position, this._indicateOption.color, POINT_OBJECT_NAME);

commitModify(index, objInfo, height, overlay)

편집 결과를 확정합니다. 편집된 좌표로 새 경로를 생성해 기존 경로와 교체하고, 편집 보조 객체들을 정리합니다.

Name Type Description
index number

항로상에 편집하려는 점의 index 번호

objInfo Object3D

편집 시에 상호작용한 구체 정보

height number

편집한 위치에 적용할 높이 (미터)

overlay U3dOverlay

편집모드에 사용된 overlay 객체

computeIntersectPoint(targetList, isSimple)Array.<Intersection>

경로(중심선)를 따라 광선을 쏘아 충돌하는 객체들을 찾아 반환합니다.

Name Type Default Description
targetList Array.<Object3D> [] optional

충돌 검사 대상 목록 (다른 경로, layer._group, 건물 등)

isSimple boolean false optional

간소화 검사 여부 (true면 더 적은 구간으로 빠르게 검사)

Returns:
Type Description
Array.<Intersection> 충돌 객체 목록

createIntersectSphere(radius, color, objName)

경로의 각 곡선 점 위치에 편집용 구체를 생성합니다.
이 구체들을 Gizmo 로 드래그해 경로를 편집할 수 있습니다.

Name Type Description
radius number

편집점 구체의 반지름 (미터)

color ColorRepresentation

편집점 구체의 색상

objName string

편집점 구체에 붙일 이름. 나중에 클릭한 대상이 편집점인지 가려낼 때 사용합니다

createMesh(opt)U3dPathGeometry|undefined

위경도 좌표(geopoints) 목록으로 경로 메시를 생성합니다.
좌표를 월드 좌표로 변환한 뒤 createMeshFromVec3 로 메시를 만듭니다.

Name Type Description
opt PathGeometryInfo optional

경로 옵션 (geopoints, pts, width, opacity, pathcolor, pathheight 등)

Returns:
Type Description
U3dPathGeometry | undefined 생성 성공 시 경로, 실패 시 undefined

createMeshFromVec3(pts, opt)U3dPathGeometry|undefined

월드 좌표 목록을 폭(buffer)만큼 확장하고 높이로 돌출시켜 경로 메시를 생성합니다. (jsts 라이브러리 필요)

Name Type Description
pts Array.<Vector3>

경로 좌표 목록 (월드 좌표, 최소 2개)

opt PathGeometryInfo optional

경로 옵션 (width, minheight, maxheight, color, opacity, edge 등)

Returns:
Type Description
U3dPathGeometry | undefined 생성 성공 시 경로, 실패 시 undefined

createPathMesh(vertices, opt)U3dPathGeometry|undefined

좌표 목록과 속성값으로 경로 메시를 생성합니다. (경로 생성의 핵심 함수)

Name Type Description
vertices Array.<Vector3>

좌표 목록 (월드 좌표, 최소 2개)

opt PathGeometryInfo

경로 속성값 (app, color, width, minheight, maxheight, tension, segments, edge 등)

Returns:
Type Description
U3dPathGeometry | undefined 생성 성공 시 경로, 실패 시 undefined
Example
let vertices= [...
     Vector3 {x: -211974.7455244285, y: 103035.01178008945, z: 225.00000000000006},
     Vector3 {x: -212428.82897879853, y: 102746.29387061192, z: 219.8797440867325},
     Vector3 {x: -212110.3113531847, y: 103221.13282597672, z: 214.64210294719626},
      ...]
  let opt = {
             app : app,
             color : PARAM['color'], // 경로 색상
             opacity : PARAM['pathopacity'], // 경로 투명도
             width : PARAM['width'], //경로 너비
             maxheight : PARAM['pathheight'], // 경로 높이
             tension : PARAM['tension'], //경로 곡선 보정 정도
             minheight : PARAM['height'], // 지면 높이
             transparent : PARAM['pathopacity'] < 1,
             segments : 200, // 경로 세분화 조각 갯수
             edge : true, // 테두리선 생성 유무
            }
let geom_ = new Union3D.geom.U3dPathGeometry().createPathMesh(vertices, opt);

deletePathChildren()

경로에 딸린 편집용 자식 객체(편집점·Gizmo 구체)를 모두 삭제합니다.

dispose()

경로와 편집용 임시 객체·이벤트를 모두 정리하고 메모리를 해제합니다.

draw(draw, opt)

마우스로 경로를 그리는 모드를 켜거나 끕니다.
켜면 클릭으로 점을 추가하고 더블클릭으로 그리기를 마칠 수 있습니다. (끄면 endPathPoint 와 동일하게 그리기를 종료)

Name Type Default Description
draw boolean true optional

그리기 시작(true) / 종료(false)

opt PathGeometryInfo optional

경로 속성 옵션 (색상, 높이, 너비 등)

endEvent(e)

그리기 모드에서 더블클릭 시 호출됩니다. 미리보기 경로를 정리하고 최종 경로를 완성합니다.
(draw 를 켤 때 dblclick 이벤트에 자동으로 연결됩니다)

Name Type Description
e U3dMouseEvent

마우스 더블클릭 이벤트 객체

endPathPoint(intersect)

경로 그리기를 종료합니다. 미리보기로 쓰던 임시 경로를 정리하고 최종 경로를 확정합니다.
path.draw(false) 를 호출하는 것과 동일하게 동작합니다.

Name Type Description
intersect Array.<Intersection> optional

그리기 종료(더블클릭) 시점의 교차 검사 결과. end 이벤트로 그대로 전달됩니다. (직접 호출 시 생략 가능)

Example
path.draw(opt);
path.addPoint(pos);            // 또는 path.updateByPoints(positionList);
// 좌표 추가를 완료한 뒤 종료 함수 호출
path.endPathPoint();           // === path.draw(false)

경로를 다시 생성하는 데 필요한 속성과 좌표를 반환합니다.
반환값을 import 에 넣으면 같은 경로를 복원할 수 있습니다.

Returns:
Type Description
U3dPathGeometryExport 경로 속성(pathOption)과 좌표(coordinates)를 담은 객체

getColor()Color|undefined

경로의 현재 색상을 반환합니다.

Returns:
Type Description
Color | undefined 경로 색상 (색상이 없으면 undefined)

getDrawModeName()string

그리기 모드의 이름 문자열('draw')을 반환합니다.

Returns:
Type Description
string 그리기 모드 이름

getDynamicSegmentValue()number

경로 세분화 기준 단위(dynamicSegmentValue)를 반환합니다.

Returns:
Type Description
number 세분화 기준 단위

getEditModeName()string

편집 모드의 이름 문자열('edit')을 반환합니다.

Returns:
Type Description
string 편집 모드 이름

getMode()string

현재 동작 모드를 반환합니다. ('draw' 그리기 / 'edit' 편집 / 'pan' 기본)

Returns:
Type Description
string 현재 모드 ('draw' / 'edit' / 'pan')

getOpacity()number

경로의 현재 투명도를 반환합니다.

Returns:
Type Description
number 투명도 (0 ~ 1)

getPanModeName()string

기본 모드의 이름 문자열('pan')을 반환합니다.

Returns:
Type Description
string 기본 모드 이름

경로의 현재 속성을 반환합니다. (setParam과 짝을 이룹니다)
반환된 객체를 그대로 setParam에 넘기면 같은 형태를 재현할 수 있습니다.

Returns:
Type Description
U3dPathGeometryParam 너비·높이·곡선 정도·세분화·외곽선 여부 등 현재 속성 객체

gizmoChangeEvent(data)

Gizmo 로 구체를 드래그하는 동안 실시간으로 호출되는 핸들러.
드래그된 위치를 경로 곡선에 반영하고 미리보기용 가이드 경로를 그려줍니다. (호출 시 모드는 EDIT_MODE 로 전환)
Gizmo 의 onChange 이벤트에 연결해 사용합니다.

Name Type Description
data Object

Gizmo 이벤트 데이터. data.target이 Gizmo 분석 객체이며, 여기서 드래그 중인 편집점 구체와 이동량을 얻습니다

gizmoEndEvent(data)

Gizmo 드래그가 끝났을 때 한 번 호출되는 핸들러.
구체의 최종 위치를 위경도 좌표로 변환해 편집 종료 콜백(_modifyEndFunction)에 전달합니다. (콜백 인자: 편집 점 index, 위경도 좌표, 구체 정보)
Gizmo 의 end 이벤트에 연결해 사용합니다.

Name Type Description
data Object

Gizmo 이벤트 데이터. data.target 이 Gizmo 분석 객체이며, 여기서 드래그 시작 위치·이동 오프셋과 편집 대상 구체를 얻는다

import(opt)U3dPathGeometry|undefined

저장된 속성과 좌표로 경로를 다시 생성(복원)합니다.
export 로 저장한 결과를 그대로 넣어 같은 경로를 재현할 수 있습니다.

Name Type Description
opt object

export가 돌려준 객체

Name Type Description
pathOption PathGeometryInfo optional

복원할 경로의 속성 (색상·외곽선·장력 등). 없으면 아무것도 만들지 않습니다

coordinates Array.<WorldPositionVector3>

경로가 지나갈 좌표 목록 (월드 좌표, EPSG:3857)

Returns:
Type Description
U3dPathGeometry | undefined 복원한 경로. pathOption이 없거나 레이어에 등록하지 않았으면 undefined
Example
let optInfo = {
     coordinates: [...position List],
     pathOption:{
         color:"#2b448b",
         edge:true,
         maxheight:10,
         minheight:100,
         opacity:0.4,
         segments:200,
         tension:0.5,
         transparent:true,
         width:20
     }
 }
  let path = new Union3D.geom.U3dPathGeometry();
  vectorLayer.addGeometry(path_);
  path.import(optInfo)

modify(intersect, endFunction)

선택한 지점에 Gizmo 편집기를 띄워 경로를 편집합니다.
편집점 구체를 드래그해 위치를 옮기며, 편집이 끝나면 endFunction 이 호출됩니다. (모드는 EDIT_MODE 로 전환)

Name Type Description
intersect object

클릭 지점의 교차 정보 하나. app.intersectAtPixel이 돌려준 배열에서 항목 하나를 골라 넘깁니다

Name Type Description
object Object3D

교차한 3D 객체. 경로 본체이거나 이미 만들어 둔 편집점 구체입니다

endFunction function

편집이 종료된 후에 동작할 함수 (편집점 index, 편집 위치의 위경도 좌표, 편집한 구체 객체가 인자로 전달됨)

Example
const intersect = app.intersectAtPixel(e, false, true);
if (!intersect || !intersect[0]) return;

let target = intersect[0].object;
if (!target.modify && target._path) target = target._path;   // 편집점을 클릭하면 경로로 되짚습니다
if (!target.modify) return;
if (target.getMode() === target.getDrawModeName()) return;   // 그리는 중이면 편집하지 않습니다

const gizmo = app.getAnalysis('GizmoModel');
gizmo.on('onChange', target.gizmoChangeEvent.bind(target));
gizmo.on('end', target.gizmoEndEvent.bind(target));

target.modify(intersect[0], (index, geoPosition) => console.log('편집 완료', index, geoPosition));

onMouseMove(event)

그리기 모드에서 마우스 이동 시 호출됩니다. 다음 점까지의 미리보기 경로와 높이 도우미를 표시합니다.
(draw 를 켤 때 mousemove 이벤트에 자동으로 연결됩니다)

Name Type Description
event U3dMouseEvent

마우스 이동 이벤트 객체

onMouseWheel(event)

그리기 모드에서 Shift + 마우스 휠로 다음에 추가될 점의 높이를 조절합니다. (높이 도우미도 함께 갱신)
(draw 를 켤 때 mousewheel 이벤트에 자동으로 연결됩니다)

Name Type Description
event WheelEvent

마우스 휠 이벤트 객체

removeModifyHelper()

경로 편집에 사용한 Gizmo 와 편집점 구체를 제거합니다.
(구체가 원래 위치와 거의 같은 곳에 있으면 의미 없는 추가로 보고 함께 정리)

removePathGeometry(scene)

경로를 화면에서 제거하고 geometry·material 등 리소스를 정리합니다.
scene 을 넘기면 해당 scene 에서, 생략하면 소속 레이어에서 제거합니다.

Name Type Description
scene Scene optional

제거할 scene, 미입력 시 소속 vectorLayer 에서 제거

setColor(color)

경로의 색상을 설정합니다.
(내부적으로 material.color 또는 material.uniforms.color.value 에 적용)

Name Type Description
color ColorRepresentation | Vector3

경로 색상. 16진수 숫자(0xff00ff), CSS 색 문자열('#ff00ff'), THREE.Color를 넣습니다. THREE.Vector3를 넘기면 x·y·z를 0~1 범위의 R·G·B로 읽습니다

setDynamicSegmentValue(value)

경로 길이에 비례해 세분화를 늘릴 기준 단위를 설정합니다. (값이 작을수록 더 촘촘하게 분할됩니다)

Name Type Description
value number

세분화 기준 단위 (경로 길이를 이 값으로 나눠 분할 수를 계산)

setMode(mode)

경로의 동작 모드를 설정합니다. ('draw' 그리기 / 'edit' 편집 / 'pan' 기본)

Name Type Description
mode string

설정할 모드 ('draw' / 'edit' / 'pan')

setOpacity(value)

경로의 투명도를 설정합니다.
1을 주면 불투명(transparent off, depthWrite on), 1 미만이면 반투명(transparent on, depthWrite off)으로 전환됩니다.

Name Type Description
value number

투명도 값 (0 ~ 1)

setParam(param)

경로의 속성(색상·투명도·너비·높이·곡선 정도 등)을 한 번에 변경합니다.
전달한 값만 반영되고 나머지는 기존 값이 유지됩니다. 색상과 투명도는 언제든 즉시 적용되지만,
형태에 영향을 주는 값(너비·높이·곡선 정도·세분화·외곽선)은 경로를 다시 만들어야 하므로 그리기가 끝난 경로에만 적용됩니다. (점이 2개 이상 있어야 합니다)

Name Type Description
param U3dPathGeometrySetParam optional

변경할 속성 객체 (색상·투명도·너비·높이·곡선 정도·세분화·외곽선)

Example
// 이미 그려 놓은 경로의 색과 너비를 바꾸기
path.setParam({color: '#ff0000', opacity: 0.6, width: 40});

updateByPoints(points)

점 좌표 목록으로 경로를 다시 계산해 갱신합니다.
이미 만들어진 경로가 없으면 이 좌표로 경로를 새로 만듭니다.

Name Type Description
points Array.<WorldPositionVector3>

경로가 지나갈 좌표 목록 (월드 좌표, EPSG:3857). 빈 배열이면 아무것도 바꾸지 않습니다

Type Definitions

PathGeometryInfoobject

PathGeometry 속성 정보

Properties:
Name Type Argument Default Description
app * <optional>

좌표 변환과 지형 조회에 사용할 앱(U3dApp). 경로를 만드는 함수는 이 값이 있어야 동작합니다

color ColorRepresentation <optional>

경로 색상

opacity number <optional>

불투명도 (0~1). 1보다 작으면 투명 처리가 켜집니다

width number <optional>

경로 너비 (미터)

minheight number <optional>

경로 아랫면의 높이 (지면 기준, 미터)

maxheight number <optional>

경로 윗면의 높이 (지면 기준, 미터)

tension number <optional>

좌표를 잇는 곡선의 팽팽함 (0~1). 클수록 직선에 가까워집니다

dynamicSegmentValue number <optional>

경로가 길어질 때 분할 수를 늘릴 기준 길이. 경로 길이를 이 값으로 나눠 분할 수를 정합니다

segments number <optional>

경로를 나눌 조각 수. 작을수록 단순해집니다

transparent boolean <optional>

재질의 투명 처리를 켤지 여부

points Array.<Vector3> <optional>

경로가 지나갈 좌표 목록 (월드 좌표, EPSG:3857)

textureUrl string <optional>

경로 표면에 입힐 이미지 URL. 넣으면 단색 대신 이 이미지를 사용합니다

pathheight number <optional>
40

경로 윗면의 높이 (미터). createMesh에서 maxheight 대신 쓰는 이름입니다

height number <optional>

경로 아랫면의 높이 (미터). 넣지 않으면 minheight 값을 씁니다

centerheight number <optional>

경로 중심의 높이 (미터). 넣으면 이 값을 기준으로 아랫면·윗면 높이를 반씩 나눠 잡습니다

addstartend boolean <optional>
false

곡선을 만들 때 시작점과 끝점을 한 번 더 넣을지 여부

buffer number <optional>

중심선을 좌우로 넓힐 거리 (미터). 넣지 않으면 width를 씁니다

pts Array.<Vector3> <optional>

곡선 계산에 쓸 좌표 목록 (월드 좌표, EPSG:3857)

geopoints Array.<GeoPositionVector3> <optional>

경로가 지나갈 위경도 좌표 목록 (EPSG:4326). createMesh가 월드 좌표로 바꿔 사용합니다

pathopacity number <optional>

불투명도 (0~1). 다른 클래스와 주고받을 때 쓰는 이름이며 경로 생성에는 사용되지 않습니다

pathcolor string <optional>
'#9f33b2'

경로 색상. createMesh에서 color 대신 쓰는 이름입니다

PathMaterialobject

~extends ShaderMaterial
~extends MeshBasicMaterial
Path Material에 원본 색상/투명도 백업 프로퍼티를 추가한 타입

PathSphereobject

~extends U3dSphere
U3dSphere에 경로 편집용 커스텀 프로퍼티를 추가한 타입

Properties:
Name Type Description
setManualUpdate function

ThreeExtend.js에서 Object3D.prototype에 추가된 수동 갱신 메서드

RoadBufferGeometryobject

~extends UExtrudeGeometry
BufferGeometry에 경로 관련 커스텀 프로퍼티를 추가한 타입

Properties:
Name Type Argument Description
sides Array.<boolean> <optional>

면별(상/좌/하/우) 생성 여부

lss number <optional>

길이 방향 정점 수 (_lengthSegments + 1)

curve CatmullRomCurve3

경로 보간 곡선

points Array.<Vector3>

곡선을 분할한 좌표 목록

len number <optional>

곡선 전체 길이

lenList Array.<number> <optional>

분할 지점별 누적 길이 목록

normals Array.<Vector3> <optional>

분할 지점별 법선 벡터

isPath boolean <optional>

경로(path) 형태 geometry 여부

faceCount number <optional>

면(삼각형) 개수

vertexCount number <optional>

정점 개수

faceIndices Uint32Array <optional>

면 인덱스 버퍼

vertices Float32Array

정점 좌표 버퍼

uvs Float32Array <optional>

UV 좌표 버퍼

U3dPathGeometryCOobject

~extends U3dGeometry~U3dGeometryCO
U3dPathGeometry 생성자 옵션

Properties:
Name Type Argument Default Description
width number <optional>
20

경로 너비 (미터)

minHeight number <optional>
0

경로 아랫면의 높이 (지면 기준, 미터)

maxHeight number <optional>
100

경로 윗면의 높이 (지면 기준, 미터)

minheight number <optional>
0

minHeight와 같은 값을 받는 소문자 이름

maxheight number <optional>
100

maxHeight와 같은 값을 받는 소문자 이름

layerName string <optional>
""

이 경로가 속할 레이어 이름

layername string <optional>
""

layerName과 같은 값을 받는 소문자 이름

tension number <optional>
0.5

좌표를 잇는 곡선의 팽팽함 (0~1). 클수록 직선에 가까워집니다

dynamicSegmentValue number <optional>
100

경로가 길어질 때 분할 수를 늘릴 기준 길이. 경로 길이를 이 값으로 나눠 분할 수를 정합니다

dynamicsegmentvalue number <optional>
100

dynamicSegmentValue와 같은 값을 받는 소문자 이름

segments number <optional>
200

경로를 나눌 조각 수. 작을수록 단순해집니다

U3dPathGeometryExportobject

U3dPathGeometry export 결과 객체

Properties:
Name Type Description
pathOption object

경로를 다시 만드는 데 필요한 속성 모음

Properties
Name Type Description
edge boolean

외곽선(테두리 선) 표시 여부

maxheight number

경로 윗면의 높이 (지면 기준, 미터)

minheight number

경로 아랫면의 높이 (지면 기준, 미터)

tension number

좌표를 잇는 곡선의 팽팽함 (0~1)

color ColorRepresentation

경로 색상

width number

경로 너비 (미터)

opacity number

불투명도 (0~1)

transparent boolean

재질의 투명 처리를 켰는지 여부

segments number

경로를 나눌 조각 수. 작을수록 단순해집니다

coordinates Array.<Vector3>

경로가 지나갈 좌표 목록 (월드 좌표, EPSG:3857)

U3dPathGeometryParamobject

getParam 함수가 반환하는 경로(Path) 속성 객체입니다.
이 객체를 다른 경로의 setParam에 그대로 넘기면 같은 형태로 맞출 수 있습니다.

Properties:
Name Type Description
width number

경로 너비 (m)

tension number

경로 휘어짐 정도 (0~1)

segments number

경로 세분화 정도

minheight number

경로 아랫면의 높이 (지면 높이, m)

maxheight number

경로 윗면의 높이 (m)

outline boolean

외곽선 표시 여부

U3dPathGeometrySetParamobject

setParam 함수에 전달하는 경로 속성 객체입니다.
높이 관련 속성은 생성 옵션(minheight/maxheight)과 예제 표기(height/pathheight)를 모두 받습니다.

Properties:
Name Type Argument Description
color ColorRepresentation <optional>

경로 색상

opacity number <optional>

투명도 (0~1, 1이면 불투명)

width number <optional>

경로 너비 (m)

tension number <optional>

경로의 곡선 정도 (0~1, 클수록 직선에 가까움)

segments number <optional>

경로 세분화 정도 (작을수록 단순화)

minheight number <optional>

경로 아랫면의 높이 (지면 높이, m)

minHeight number <optional>

minheight와 동일 (카멜케이스 표기)

height number <optional>

minheight와 동일 (지면 높이)

maxheight number <optional>

경로 윗면의 높이 (m)

maxHeight number <optional>

maxheight와 동일 (카멜케이스 표기)

pathheight number <optional>

maxheight와 동일 (경로 높이)