GeOnDT GeOnDT for JS

Class: U3dPoint

U3dPoint

~extends U3dGeometry
3D 공간의 한 점(또는 여러 점)을 이미지 마커로 표시하는 도형 클래스입니다.
각 점은 항상 화면을 향하는 스프라이트 형태로 그려지며, 이미지·크기 등을 지정할 수 있습니다.

new U3dPoint(opt)

포인트 도형을 생성합니다.
색상·크기·이미지(img) 등을 옵션으로 지정할 수 있으며, 좌표는 생성 후 setVertex(월드)나 setPositions(위경도)로 넣습니다.

Name Type Default Description
opt U3dPoint~U3dPointCO {} optional

생성 옵션

Members

DEFAULT_ALPHA_TESTnumber

Point 재질의 alphaTest 기본값. 이미지의 반투명 가장자리를 잘라내는 임계값입니다.

depthTestboolean

깊이 판정 사용 여부 (기본값 true). false면 다른 객체에 가려지지 않고 항상 위에 그려집니다. 변경은 setDepthTest/setParam으로 합니다.

imgstring HTMLImageElement undefined

Point에 적용할 이미지 URL 또는 이미지 엘리먼트. 변경은 setImage로 합니다.

materialListRecord.<string, (PointsMaterial|undefined)>

이미지 URL(+offset)을 키로 하는 Point 재질 캐시.
setImage가 URL 이미지를 처음 로드하면 등록되고, 이후 같은 키는 이 재질을 clone하여 재사용합니다. 캐시 항목의 재질·텍스처는 캐시가 소유하므로 개별 인스턴스의 dispose로는 해제되지 않으며, disposeMaterialList로 전체를 정리합니다. 키는 #cacheKey로 만들며 offset이 있으면 url|x,y 형태입니다.

offsetVector3Like undefined

이미지 위치 보정 비율. 이미지 폭·높이에 곱한 만큼 기준점이 이동하며, 양수는 오른쪽·아래로, 음수는 왼쪽·위로 치우칩니다. z는 사용하지 않습니다.
이동한 만큼 캔버스가 확장되어 실제 표시 크기도 함께 커지며, URL 이미지 로드 시에만 적용됩니다. 변경은 setOffset/setParam으로 합니다.

sizenumber

Point 크기 요청값 (기본값 1). sizeAttenuation이 false면 화면 픽셀, true면 월드 단위(미터)로 해석됩니다.
offset으로 이미지가 확장되면 실제 표시 크기는 이 값에 배율이 곱해지므로, 실제 표시 크기는 getSize로 확인합니다. 직접 대입하면 재질에 반영되지 않으므로 변경은 setSize/setParam으로 합니다.

sizeAttenuationboolean

카메라 거리에 따라 Point 크기를 감쇠할지 여부 (기본값 false). 변경은 setSizeAttenuation/setParam으로 합니다.

Methods

dispose()

3D 포인트를 화면에서 제거하고 관련 리소스(지오메트리·재질·인스턴스 소유 텍스처)를 해제합니다.
호출 후 인스턴스는 재사용할 수 없습니다. 재질 캐시(materialList)가 소유한 공유 텍스처는 해제하지 않으며, disposeMaterialList로 정리합니다.

getDepthTest()boolean

깊이 판정 사용 여부를 반환합니다.

Returns:
Type Description
boolean

getOffset()Vector3Like|undefined

이미지 위치 보정 비율을 반환합니다.

Returns:
Type Description
Vector3Like | undefined

getParam()U3dPoint~U3dPointParam

포인트의 현재 속성을 반환합니다. (setParam에 다시 넘길 수 있습니다)

Returns:
Type Description
U3dPoint~U3dPointParam 크기·이미지·깊이 판정 등 현재 속성 객체

getSize()number

포인트의 실제 표시 크기를 반환합니다. (요청 크기 size × offset 확장 배율)

Returns:
Type Description
number Point 크기. 단위는 size 프로퍼티와 같이 sizeAttenuation에 따라 픽셀 또는 미터 (설정값이 없으면 0)

getSizeAttenuation()boolean

카메라 거리에 따른 크기 감쇠 여부를 반환합니다.

Returns:
Type Description
boolean

setDepthTest(val)

깊이 판정 사용 여부를 설정합니다. false면 다른 객체에 가려지지 않고 항상 위에 그려집니다. 재질에 즉시 반영됩니다.

Name Type Description
val boolean

setImage(img)

3D 포인트에 이미지 텍스처를 적용합니다.
문자열 URL을 주면 비동기로 로드해 적용하고, 이미지 엘리먼트를 주면 즉시 적용합니다. 이미지 로드가 끝나면 포인트가 화면에 표시되고 change 이벤트가 발생합니다. 로드에 실패하면 오류를 기록하고 이미지 없는 색상 점으로 표시합니다.
주의 사항: 같은 URL(+offset)이 materialList에 캐시되어 있으면 material이 캐시의 clone으로 교체되므로, 기존 material 참조는 다시 얻어야 합니다. 교체 시 현재 인스턴스의 color·size·sizeAttenuation·depthTest는 새 재질에 그대로 유지됩니다. offset이 있으면 확장된 이미지 비율만큼 실제 표시 크기가 조정되고(getSize), 이미지 엘리먼트를 주면 size가 이미지 폭으로 설정됩니다. 인스턴스가 소유한 기존 texture는 해제(dispose)되며, 캐시가 소유한 텍스처는 해제하지 않습니다.

Name Type Description
img string | HTMLImageElement

이미지 URL 또는 이미지 엘리먼트

setOffset(offset)

이미지 위치 보정 비율을 설정합니다. URL 이미지가 적용된 상태면 이미지를 다시 적용하여 즉시 반영합니다.

Name Type Description
offset Vector3Like | undefined

setParam(param)

포인트의 속성을 한 번에 변경합니다.
부모 속성(색상·투명도 등)에 더해 size, sizeAttenuation, depthTest를 재질에 즉시 반영하고, img나 offset이 실제로 바뀐 경우에만 setImage를 다시 호출합니다. heightOffset, renderOrder는 생성 시에만 적용되어 여기서 변경되지 않습니다.

Name Type Description
param U3dPoint~U3dPointCO optional

변경할 속성 객체. 생략한 속성은 현재 값을 유지합니다

setSize(size)

3D 포인트의 크기를 설정합니다.
재질(PointsMaterial)의 size에 즉시 반영됩니다. offset 확장 배율은 자동으로 곱해집니다.

Name Type Description
size number

새로 설정할 크기. sizeAttenuation이 false면 화면 픽셀, true면 월드 단위(미터)

setSizeAttenuation(val)

카메라 거리에 따른 크기 감쇠 여부를 설정합니다. 재질에 즉시 반영됩니다.
단위 해석이 바뀌므로(픽셀 ↔ 미터) 필요하면 setSize로 크기를 함께 조정합니다.

Name Type Description
val boolean

updateSize(size)

3D 포인트의 크기를 갱신합니다. (setSize와 동일)

Name Type Description
size number

새로 설정할 크기. 단위는 setSize와 같음
Deprecated
  • `setSize`를 사용하세요. 동일한 동작의 중복 메서드입니다.

    static disposeMaterialList()

    캐시된 Point 재질(materialList)과 그 텍스처를 모두 정리(dispose)합니다.
    캐시 텍스처는 살아있는 U3dPoint 인스턴스들이 공유하므로, 앱 종료나 전체 리셋 시점에만 호출해야 합니다.

    Type Definitions

    U3dPointCOobject

    ~extends U3dGeometry~U3dGeometryCO
    U3dPoint 생성자 옵션

    Properties:
    Name Type Argument Default Description
    size number <optional>
    		 1

    Point 크기. sizeAttenuation이 false면 화면 픽셀, true면 월드 단위(미터)로 해석됩니다.
    img string | HTMLImageElement <optional>

    Point 이미지 URL 또는 이미지 엘리먼트
    offset Vector3Like <optional>

    Point 이미지 위치 보정 비율. 이미지 폭·높이에 곱한 만큼 기준점이 이동하며, 양수는 오른쪽·아래로, 음수는 왼쪽·위로 치우칩니다. z는 사용하지 않음. 이동한 만큼 실제 표시 크기도 함께 커집니다(getSize 참고). ex: {x:0.5, y:0.5, z:0}
    sizeAttenuation boolean <optional>
    		 false

    카메라에서 멀어질수록 Point를 작게 그릴지 여부
    depthTest boolean <optional>
    		 true

    깊이 판정 사용 여부. false면 다른 객체에 가려지지 않고 항상 위에 그려집니다
    heightOffset number <optional>

    높이 보정값 (월드 z, 미터). 생성 시 한 번만 적용되며 setParam으로 변경되지 않음
    renderOrder number <optional>
    		 0

    렌더 순서. 값이 클수록 나중에 그려져 같은 위치의 다른 객체 위에 보입니다. 생성 시 한 번만 적용되며 setParam으로 변경되지 않음

    U3dPointParamobject

    getParam 함수가 반환하는 Point 속성 객체

    Properties:
    Name Type Description
    size number

    Point 크기(요청값). 단위는 sizeAttenuation에 따라 픽셀 또는 미터 (U3dPointCO.size 참고)
    img string | HTMLImageElement | undefined

    Point 이미지 URL 또는 이미지 엘리먼트
    offset Vector3Like | undefined

    Point 이미지 위치 보정 비율 (U3dPointCO.offset 참고)
    sizeAttenuation boolean

    카메라에서 멀어질수록 Point를 작게 그릴지 여부
    depthTest boolean

    깊이 판정 사용 여부. false면 다른 객체에 가려지지 않고 항상 위에 그려집니다