> For the complete documentation index, see [llms.txt](https://egiscorp.gitbook.io/xdworld-webgl-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://egiscorp.gitbook.io/xdworld-webgl-manual/api/etc/jsmath.md).

# JSMath

수학적 알고리즘 처리를 위한 API 입니다.

> Module.getMath() API를 생성합니다.

```javascript
var math = Module.getMath();
```

### convertBezierCurve(options) → [JSVec3Array](https://github.com/EgisCorp/XDWorld_WebGL_Manual/blob/master/core/JSVec3Array.md)

> 경위도 좌표 목록 정보를 통해 베지어 곡선이 적용된 좌표 목록 반환합니다..
>
> argument 변수로 좌표 변환 옵션을 설정합니다.

{% tabs %}
{% tab title="Information" %}

| Name   | Type                                      | Description |
| ------ | ----------------------------------------- | ----------- |
| option | [JSMath.BezierCurve](#jsmath.beziercurve) | 속성 정보.      |

* Return
  * [JSVec3Array](https://github.com/EgisCorp/XDWorld_WebGL_Manual/blob/master/core/JSVec3Array.md): 변환 성공
  * size 0: 변환 실패.
* Sample
  * function createCurvedLine 참조.
  * [Sandbox\_LineInterpolation(Curved)](https://sandbox.egiscloud.com/code/main.do?id=object_line_interpolate_curved)
    {% endtab %}

{% tab title="Template" %}

```javascript
var vertices = [];

vertices.push([lon, lat, alt]);
vertices.push([lon, lat, alt]);
vertices.push([lon, lat, alt]);

let curve_pos = {
    coordinate: vertices,
    style: "XYZ",
};
```

{% endtab %}
{% endtabs %}

### convertBeZierLine(options) → object

> 시작, 끝 경위도 좌표도 기준으로 베지어 곡선 좌표 목록을 반환합니다.
>
> argument 변수로 좌표 변환 옵션을 설정합니다.

{% tabs %}
{% tab title="Information" %}

| Name   | Type                                    | Description |
| ------ | --------------------------------------- | ----------- |
| option | [JSMath.BezierLine](#jsmath.bezierline) | 속성 정보.      |

* Return
  * .result: API 성공 유무 상태 ( 1 : 성공, 0 : 실패 ).
  * .name: 동작 API 명칭.
  * .return: API 반환 정보 ( object : 정상적인 반환값, 문자열 : 실패 에러 코드 ).
* Sample
  * function createBallPath 참조
  * [Sandbox\_ParabolicLine](https://sandbox.egiscloud.com/code/main.do?id=object_line_arc)
    {% endtab %}

{% tab title="Template" %}

```javascript
let parameters = {
    start: new Module.JSVector3D(127.94080035885989, 36.336424549396064, 306.52637346833944),
    end: new Module.JSVector3D(127.9419239501012, 36.33615414434727, 300.5711971661076),
    detail: 100,
    height: 330,
    percent: 70,
};
```

{% endtab %}
{% endtabs %}

### convertCatmullRom(options) → object

> 좌표 목록으로 Catmull-Rom 곡선을 생성합니다. RDP 알고리즘 기반 좌표 간소화, 지형 결합 옵션을 지원합니다.

{% tabs %}
{% tab title="Information" %}

| Name    | Type   | Description                                                                                                                                                                                                        |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| options | object | `coordinates`(필수, `{style, coordinate}`), `alpha`(0~~1), `tension`(0~~1), `samples`(구간별 샘플 수, 기본 20), `simplify`(RDP 간소화 여부), `epsilon`(RDP 간소화 허용 오차), `union`(지형 결합 여부), `height`(지형 결합 시 추가 높이) 속성을 포함하는 옵션 객체. |

* Return
  * `.result`: API 성공 유무 (1: 성공, 0: 실패).
  * `.name`: 동작 API 명칭.
  * `.simplified`: RDP 간소화가 적용된 원본 제어점 목록 ([JSVec3Array](/xdworld-webgl-manual/api/core/jsvec3array.md)).
  * `.position`: 생성된 Catmull-Rom 곡선 좌표 목록 ([JSVec3Array](/xdworld-webgl-manual/api/core/jsvec3array.md)).
  * `.times`: 각 좌표까지의 누적 거리 목록 (array).
    {% endtab %}

{% tab title="Template" %}

```javascript
let option = {
    coordinates: { style: "XYZ", coordinate: [[127.0, 37.5, 10], [127.01, 37.51, 10], [127.02, 37.49, 10]] },
    samples: 20,
    alpha: 0.5,
};
let result = Module.getMath().convertCatmullRom(option);
```

{% endtab %}
{% endtabs %}

### calculationSlopeAnalysis(options) → object

> 3\*3(0 배열 좌상단 9 배열 우하단) 배열값을 통한 경사 분석 결과 반환.
>
> argument 변수로 좌표 변환 옵션을 설정합니다.

{% tabs %}
{% tab title="Information" %}

| Name   | Type                                      | Description |
| ------ | ----------------------------------------- | ----------- |
| option | [JSMath.SlopeOption](#jsmath.slopeoption) | 속성 정보.      |

* Return
  * .result: API 성공 유무 상태 ( 1 : 성공, 0 : 실패 ).
  * .name: 동작 API 명칭.
  * .return: API 반환 정보 ( object : 정상적인 반환값, 문자열 : 실패 에러 코드 ).
    {% endtab %}

{% tab title="Template" %}

```javascript
let slop = {
    type: "TERRAIN_DIRECTION_ANGLE",
    array: [101, 92, 85, 101, 92, 85, 101, 91, 84],
    vertical: 10,
    horizontal: 10,
};
let result = Module.getMath().calculationSlopeAnalysis(slop);
```

{% endtab %}
{% endtabs %}

### splitLine(options) → object

> 이 함수는 `Module.JSMath.splitLine(...)`로 호출해야 합니다.
>
> 경위도 좌표 목록을 일정 간격으로 분할한 결과를 반환합니다.

{% tabs %}
{% tab title="Information" %}

| Name    | Type   | Description                              |
| ------- | ------ | ---------------------------------------- |
| options | object | `coordinates` 정보와 `split` 수치를 포함한 옵션 객체. |

* options 구조

| Key         | Type   | Description                    |
| ----------- | ------ | ------------------------------ |
| coordinates | object | 좌표 정보 `{ style, coordinate }`. |
| split       | number | 나눌 정점 개수. 기본값: 100             |

* Return
  * `.result`: API 성공 여부 (1: 성공, 0: 실패)
  * `.name`: API 명칭
  * `.return`: `{ length, count, data }` 객체 반환
    * `length`: 전체 거리 (meter)
    * `count`: 좌표 개수
    * `data`: [JSVec3Array](https://github.com/EgisCorp/XDWorld_WebGL_Manual/blob/master/core/JSVec3Array.md) 형태의 분할 좌표
      {% endtab %}

{% tab title="Template" %}

```javascript
let coordinates = {
    style: "XYZ",
    coordinate: [
        [127.0, 37.5, 10],
        [127.001, 37.501, 10]
    ]
};

let option = {
    coordinates: coordinates,
    split: 10
};

let result = Module.JSMath.splitLine(option);
```

{% endtab %}
{% endtabs %}

### getDistance2D(point0, point1) → number

> 두 지점 간의 지형(고도) 결합 거리를 반환합니다 (입력 좌표 자체의 고도값은 사용하지 않고, 각 지점의 지형 고도를 조회하여 계산).

{% tabs %}
{% tab title="Information" %}

| Name   | Type                                                       | Description     |
| ------ | ---------------------------------------------------------- | --------------- |
| point0 | [JSVector2D](/xdworld-webgl-manual/api/core/jsvector2d.md) | 시작 좌표 (경도, 위도). |
| point1 | [JSVector2D](/xdworld-webgl-manual/api/core/jsvector2d.md) | 종료 좌표 (경도, 위도). |

* Return
  * number: 두 지점 간 거리 (meter 단위, 지형 고도 반영).
    {% endtab %}

{% tab title="Template" %}

```javascript
let d = Module.getMath().getDistance2D(new Module.JSVector2D(127.0, 37.5), new Module.JSVector2D(127.01, 37.51));
```

{% endtab %}
{% endtabs %}

### getDistance3D(point0, point1) → number

> 두 지점(경도, 위도, 고도) 간의 직선 거리를 반환합니다.

{% tabs %}
{% tab title="Information" %}

| Name   | Type                                                       | Description         |
| ------ | ---------------------------------------------------------- | ------------------- |
| point0 | [JSVector3D](/xdworld-webgl-manual/api/core/jsvector3d.md) | 시작 좌표 (경도, 위도, 고도). |
| point1 | [JSVector3D](/xdworld-webgl-manual/api/core/jsvector3d.md) | 종료 좌표 (경도, 위도, 고도). |

* Return
  * number: 두 지점 간 직선 거리 (meter 단위).
    {% endtab %}

{% tab title="Template" %}

```javascript
let d = Module.getMath().getDistance3D(new Module.JSVector3D(127.0, 37.5, 10), new Module.JSVector3D(127.01, 37.51, 20));
```

{% endtab %}
{% endtabs %}

### getCubeBuffer(options) → array

> 시작-끝 두 지점을 잇는 선을 기준으로, xRadius/yRadius 만큼 떨어진 8개의 정점 좌표(경도, 위도, 고도가 반복된 flat 배열)를 반환합니다.

{% tabs %}
{% tab title="Information" %}

| Name    | Type   | Description                                                                                   |
| ------- | ------ | --------------------------------------------------------------------------------------------- |
| options | object | `from`(시작 좌표 \[x,y,z] 배열), `to`(끝 좌표 \[x,y,z] 배열), `xRadius`, `yRadius`(반경 값) 속성을 포함하는 옵션 객체. |

* Return
  * array: `[lon, lat, alt, lon, lat, alt, ...]` 형태의 8개 정점 좌표 (flat 배열).
  * null: `from`, `to`, `xRadius`, `yRadius` 중 하나라도 누락된 경우.
    {% endtab %}

{% tab title="Template" %}

```javascript
let option = {
    from: [127.0, 37.5, 10],
    to: [127.01, 37.51, 10],
    xRadius: 2,
    yRadius: 2,
};
let buffer = Module.getMath().getCubeBuffer(option);
```

{% endtab %}
{% endtabs %}

### transformBeZierCurve(options) → object

> 이 함수는 `Module.JSMath.transformBeZierCurve(...)`로 호출해야 합니다.
>
> 다각형 좌표 목록을 베지어 곡선으로 변환하고, 변환된 곡선의 전체 길이와 좌표 목록을 반환합니다.

{% tabs %}
{% tab title="Information" %}

| Name    | Type   | Description                                                                                         |
| ------- | ------ | --------------------------------------------------------------------------------------------------- |
| options | object | `coordinates`(필수, `{style, coordinate}`, 3개 이상), `detail`(보간 점 수, 기본값 = 20 \* 정점 수) 속성을 포함하는 옵션 객체. |

* Return
  * `.result`: API 성공 유무 (1: 성공, 0: 실패).
  * `.name`: 동작 API 명칭.
  * `.return.length`: 변환된 곡선의 전체 길이.
  * `.return.count`: 변환된 좌표 개수.
  * `.return.data`: 변환된 좌표 목록 ([JSVec3Array](/xdworld-webgl-manual/api/core/jsvec3array.md)).
    {% endtab %}

{% tab title="Template" %}

```javascript
let option = {
    coordinates: { style: "XYZ", coordinate: [[127.0, 37.5, 10], [127.01, 37.51, 10], [127.02, 37.49, 10]] },
};
let result = Module.JSMath.transformBeZierCurve(option);
```

{% endtab %}
{% endtabs %}

### triangulatePointsToConvexHull(positions) → array

> 이 함수는 `Module.JSMath.triangulatePointsToConvexHull(...)`로 호출해야 합니다.
>
> 입력한 좌표 목록을 삼각분할하여 인덱스 목록을 반환합니다.

{% tabs %}
{% tab title="Information" %}

| Name      | Type                                                              | Description          |
| --------- | ----------------------------------------------------------------- | -------------------- |
| positions | Array<[JSVector3D](/xdworld-webgl-manual/api/core/jsvector3d.md)> | 삼각분할할 좌표 목록 (3개 이상). |

* Return
  * array: 삼각형을 구성하는 정점 인덱스 목록 (3개씩 하나의 삼각형).
  * null: 입력이 배열이 아니거나, 중복 제거 후 좌표가 3개 미만인 경우.
    {% endtab %}

{% tab title="Template" %}

```javascript
let positions = [
    new Module.JSVector3D(127.0, 37.5, 0),
    new Module.JSVector3D(127.01, 37.5, 0),
    new Module.JSVector3D(127.01, 37.51, 0),
    new Module.JSVector3D(127.0, 37.51, 0),
];
let indices = Module.JSMath.triangulatePointsToConvexHull(positions);
```

{% endtab %}
{% endtabs %}

### triangulatePolygonWithInnerPoints(polygonPoints, innerPoints) → object

> 이 함수는 `Module.JSMath.triangulatePolygonWithInnerPoints(...)`로 호출해야 합니다.
>
> 폴리곤 외곽 좌표와 내부 좌표를 함께 사용하여 삼각분할을 수행합니다 (Constrained Delaunay Triangulation).

{% tabs %}
{% tab title="Information" %}

| Name          | Type  | Description                                          |
| ------------- | ----- | ---------------------------------------------------- |
| polygonPoints | array | 폴리곤 외곽 좌표 목록, `[[lon, lat(, alt)], ...]` 형태 (3개 이상). |
| innerPoints   | array | 폴리곤 내부에 포함될 좌표 목록, `[[lon, lat(, alt)], ...]` 형태.    |

* Return
  * `.index`: 삼각형을 구성하는 정점 인덱스 목록 (3개씩 하나의 삼각형, 폴리곤 내부에 속하는 삼각형만 포함).
  * `.vertex`: 전체 정점 좌표 목록 (외곽 + 내부, [JSVector3D](/xdworld-webgl-manual/api/core/jsvector3d.md) 배열).
  * null: polygonPoints가 배열이 아니거나 유효한 좌표가 3개 미만인 경우.
    {% endtab %}

{% tab title="Template" %}

```javascript
let polygon = [[127.0, 37.5], [127.01, 37.5], [127.01, 37.51], [127.0, 37.51]];
let inner = [[127.005, 37.505]];
let result = Module.JSMath.triangulatePolygonWithInnerPoints(polygon, inner);
```

{% endtab %}
{% endtabs %}

### testParse(parameter)

> 이 함수는 `Module.JSMath.testParse(...)`로 호출해야 합니다.
>
> 내부 파라미터 파싱(ConvertVal) 기능 검증을 위한 디버그/테스트 전용 함수입니다. 반환값 없이 각 파싱 결과를 콘솔(printf)에 출력합니다. 프로덕션 API 용도가 아닙니다.

{% tabs %}
{% tab title="Information" %}

| Name         | Type   | Description   |
| ------------ | ------ | ------------- |
| parameter    | object | 테스트할 파라미터 객체. |
| {% endtab %} |        |               |

{% tab title="Template" %}

```javascript
```

{% endtab %}
{% endtabs %}

### Type Definitions

#### JSMath.BezierCurve

> 경위도 좌표 목록 정보를 베지어 곡선 변환 옵션.

| Name   | Type                                                                           | Attributes | Default | Description             |
| ------ | ------------------------------------------------------------------------------ | ---------- | ------- | ----------------------- |
| option | [coordinates Type](/xdworld-webgl-manual/api/etc/tag-list.md#coordinates-type) |            |         | 경위도 좌표 목록, 좌표 목록 타입 설정. |

#### JSMath.BezierLine

> 경위도 좌표 목록 정보를 포물선 곡선 변환 옵션.

| Name    | Type                                                       | Attributes | Default | Description                              |
| ------- | ---------------------------------------------------------- | ---------- | ------- | ---------------------------------------- |
| start   | [JSVector3D](/xdworld-webgl-manual/api/core/jsvector3d.md) |            | 500     | 직선 경위도 시작 위치.                            |
| end     | [JSVector3D](/xdworld-webgl-manual/api/core/jsvector3d.md) |            | 10      | 직선 경위도 끝 위치.                             |
| detail  | number                                                     | optional   | 50      | 곡선 생성 보간 점 수.                            |
| height  | number                                                     | optional   | 100     | 곡선 최대 높이.                                |
| percent | number                                                     | optional   | 50      | 시작 위치 0%, 끝 위치 100% 기준으로 곡선 최대 높이 지점 설정. |

### GetIntervalPositionInRect(min, max, vertical, horizontal) → object

> 경위도 기준의 사각 영역 내에서 일정 간격마다 좌표를 균등 분포로 반환합니다.

{% tabs %}
{% tab title="Information" %}

| Name       | Type                                                       | Description            |
| ---------- | ---------------------------------------------------------- | ---------------------- |
| min        | [JSVector2D](/xdworld-webgl-manual/api/core/jsvector2d.md) | 사각 영역의 최소 좌표 (경도, 위도). |
| max        | [JSVector2D](/xdworld-webgl-manual/api/core/jsvector2d.md) | 사각 영역의 최대 좌표 (경도, 위도). |
| vertical   | number                                                     | 세로 간격 (meter 단위).      |
| horizontal | number                                                     | 가로 간격 (meter 단위).      |

* Return
  * `position`: [JSVec2Array](/xdworld-webgl-manual/api/core/jsvec2array.md) 타입의 좌표 목록
  * `positionCountWidth`: 가로 개수
  * `positionCountHeight`: 세로 개수
    {% endtab %}

{% tab title="Template" %}

```javascript
let min = new Module.JSVector2D(127.0, 37.5);
let max = new Module.JSVector2D(127.01, 37.51);

let result = Module.getMath().GetIntervalPositionInRect(min, max, 10, 10);
```

{% endtab %}
{% endtabs %}

### isPointInPolygon(polygon, points) → Array

> 주어진 2D 포인트들이 폴리곤 내부에 포함되는지를 판별합니다.

{% tabs %}
{% tab title="Information" %}

| Name    | Type                                                         | Description          |
| ------- | ------------------------------------------------------------ | -------------------- |
| polygon | [JSVec2Array](/xdworld-webgl-manual/api/core/jsvec2array.md) | 다각형 영역 경계 좌표 목록.     |
| points  | Array<\[number, number]>                                     | 경위도 좌표 쌍(경도, 위도) 목록. |

* Return
  * `Array<boolean>`: 각 포인트가 폴리곤 안에 포함되는 여부를 `true` 또는 `false`로 반환하는 배열.
    {% endtab %}

{% tab title="Template" %}

```javascript
let polygon = new Module.JSVec2Array();
polygon.push(new Module.JSVector2D(127.0, 37.5));
polygon.push(new Module.JSVector2D(127.01, 37.5));
polygon.push(new Module.JSVector2D(127.01, 37.51));
polygon.push(new Module.JSVector2D(127.0, 37.51));

let points = [
    [127.005, 37.505],   // 내부
    [127.02, 37.52]      // 외부
];

let result = Module.getMath().isPointInPolygon(polygon, points);
// result => [true, false]
```

{% endtab %}
{% endtabs %}

### getClosestPositionOnPath(point, path) → object

> 한 점에서부터 path 까지의 거리 중 가장 가까운 위치의 정보를 반환합니다.

{% tabs %}
{% tab title="Information" %}

| Name  | Type                                                         | Description |
| ----- | ------------------------------------------------------------ | ----------- |
| point | [JSVector3D](/xdworld-webgl-manual/api/core/jsvector3d.md)   | 기준 점        |
| path  | [JSVec3Array](/xdworld-webgl-manual/api/core/jsvec3array.md) | path array  |

* Description
  * 가장 가까운 점이 선분 범위 밖에 위치하는 경우 path의 시작점 또는 끝점을 반환합니다.
  * 가장 가까운 점이 선분 내에 위치하는 경우 해당 지점의 좌표 정보를 반환합니다.
* Return
  * object
    * distance : 거리
    * position : 좌표
    * index : path 인덱스
      {% endtab %}

{% tab title="Template" %}

```javascript
let point = new Module.JSVector3D(127.003, 37.49, 10);
let path = new Module.JSVec3Array();
path.push(new Module.JSVector2D(127.0, 37.5));
path.push(new Module.JSVector2D(127.01, 37.5));
path.push(new Module.JSVector2D(127.01, 37.51));
path.push(new Module.JSVector2D(127.0, 37.51));

let closestPosition = Module.getMath().getClosestPositionOnPath(point, path);
// closestPosition.distance
// closestPosition.position
// closestPosition.index
```

{% endtab %}
{% endtabs %}

### getScreenEdgeIndicator(position) → object | null

> 화면 밖에 있는 객체의 위치를 화면 경계 기준으로 보정하여 반환합니다.

{% tabs %}
{% tab title="Information" %}

| Name     | Type                                                       | Description                 |
| -------- | ---------------------------------------------------------- | --------------------------- |
| position | [JSVector3D](/xdworld-webgl-manual/api/core/jsvector3d.md) | 대상 객체의 지형 상 위치(경도, 위도, 고도). |

* Return
  * `object`: `{ x, y }` 화면 경계상의 좌표 (픽셀 단위).
  * `null`: 객체가 화면 내에 이미 포함되어 있는 경우.
* Sample
  * function getOutOfScreenIndicator 참조
  * [Sandbox\_Object Indicator](https://sandbox.egiscloud.com/code/main.do?id=coordinate_indicator)
    {% endtab %}

{% tab title="Template" %}

```javascript
let position = new Module.JSVector3D(127.01, 37.51, 300.0);
let screenEdge = Module.getMath().getScreenEdgeIndicator(position);

if (screenEdge !== null) {
    console.log("Out of view. Indicator at:", screenEdge.x, screenEdge.y);
}
```

{% endtab %}
{% endtabs %}

#### JSMath.SlopeOption

> 경사 분석 설정 옵션.

| Name       | Type   | Attributes | Default | Description                                                             |
| ---------- | ------ | ---------- | ------- | ----------------------------------------------------------------------- |
| type       | string |            |         | 경사분석 옵션(TERRAIN\_ANGLE, TERRAIN\_DIRECTION, TERRAIN\_DIRECTION\_ANGLE). |
| array      | array  |            |         | 경사분석을 위한 \[3\*3] 해발고도 배열.                                               |
| vertical   | number | optional   | 5       | 경사도 분석에 필요한 Cell 세로 길이(단위 : m).                                         |
| horizontal | number | optional   | 5       | 경사도 분석에 필요한 Cell 세로 길이(단위 : m).                                         |