From fd7722faa0810e9b120c0e2dd522813dcb30afa9 Mon Sep 17 00:00:00 2001 From: Andrew Kao Date: Wed, 28 Sep 2022 06:21:53 +0000 Subject: [PATCH] Add documents for geojson --- .../maps-common/review/maps-common.api.md | 8 ---- sdk/maps/maps-common/src/models/geojsons.ts | 44 ++++++++++++++----- 2 files changed, 33 insertions(+), 19 deletions(-) diff --git a/sdk/maps/maps-common/review/maps-common.api.md b/sdk/maps/maps-common/review/maps-common.api.md index 203f6b19b30c..799c31d9b313 100644 --- a/sdk/maps/maps-common/review/maps-common.api.md +++ b/sdk/maps/maps-common/review/maps-common.api.md @@ -110,7 +110,6 @@ export interface GeoJsonGeometryCollection extends GeoJsonObject { // @public export interface GeoJsonLineString extends GeoJsonObject { - // (undocumented) coordinates: Position[]; // (undocumented) type: "LineString"; @@ -118,7 +117,6 @@ export interface GeoJsonLineString extends GeoJsonObject { // @public export interface GeoJsonMultiLineString extends GeoJsonObject { - // (undocumented) coordinates: Position[][]; // (undocumented) type: "MultiLineString"; @@ -126,7 +124,6 @@ export interface GeoJsonMultiLineString extends GeoJsonObject { // @public export interface GeoJsonMultiPoint extends GeoJsonObject { - // (undocumented) coordinates: Position[]; // (undocumented) type: "MultiPoint"; @@ -134,7 +131,6 @@ export interface GeoJsonMultiPoint extends GeoJsonObject { // @public export interface GeoJsonMultiPolygon extends GeoJsonObject { - // (undocumented) coordinates: Position[][][]; // (undocumented) type: "MultiPolygon"; @@ -142,15 +138,12 @@ export interface GeoJsonMultiPolygon extends GeoJsonObject { // @public export interface GeoJsonObject { - // (undocumented) bbox?: BBox; - // (undocumented) type: GeoJsonType; } // @public export interface GeoJsonPoint extends GeoJsonObject { - // (undocumented) coordinates: Position; // (undocumented) type: "Point"; @@ -158,7 +151,6 @@ export interface GeoJsonPoint extends GeoJsonObject { // @public export interface GeoJsonPolygon extends GeoJsonObject { - // (undocumented) coordinates: Position[][]; // (undocumented) type: "Polygon"; diff --git a/sdk/maps/maps-common/src/models/geojsons.ts b/sdk/maps/maps-common/src/models/geojsons.ts index 5916fae35efd..ec224d89d650 100644 --- a/sdk/maps/maps-common/src/models/geojsons.ts +++ b/sdk/maps/maps-common/src/models/geojsons.ts @@ -35,9 +35,12 @@ export type BBox3D = [ /** Bounding box including information on the coordinate range for its geometries */ export type BBox = BBox2D | BBox3D; -/** A GeoJSON object */ +/** A GeoJSON object represents a Geometry, Feature, or collection of + Features. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3) */ export interface GeoJsonObject { + /** Representing the type of this GeoJSON object, including the seven geometry type and "Feature", "FeatureCollection". [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-1.4) */ type: GeoJsonType; + /** Include information on the coordinate range for its Geometries, Features, or FeatureCollections. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-5) */ bbox?: BBox; } /** 2D position */ @@ -47,39 +50,53 @@ export type Position3D = [longitude: number, latitude: number, elevation: number /** An array of number representing a point */ export type Position = Position2D | Position3D; -/** GeoJSON Point */ +/** GeoJSON Point. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.2) */ export interface GeoJsonPoint extends GeoJsonObject { type: "Point"; + /** For type "Point", the "coordinates" member is a single position. */ coordinates: Position; } -/** GeoJSON MultiPoint */ +/** GeoJSON MultiPoint. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.3) */ export interface GeoJsonMultiPoint extends GeoJsonObject { type: "MultiPoint"; + /** For type "MultiPoint", the "coordinates" member is an array of positions. */ coordinates: Position[]; } -/** GeoJSON LineString */ +/** GeoJSON LineString. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.4) */ export interface GeoJsonLineString extends GeoJsonObject { type: "LineString"; + /** For type "LineString", the "coordinates" member is an array of two or more positions. */ coordinates: Position[]; } -/** GeoJSON MultiLineString */ +/** GeoJSON MultiLineString. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.5) */ export interface GeoJsonMultiLineString extends GeoJsonObject { type: "MultiLineString"; + /** For type "MultiLineString", the "coordinates" member is an array of LineString coordinate arrays. */ coordinates: Position[][]; } -/** GeoJSON Polygon */ +/** + * GeoJSON Polygon. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.6) + * + * To specify a constraint specific to Polygons, it is useful to introduce the concept of a linear ring: + * - A linear ring is a closed LineString with four or more positions. + * - The first and last positions are equivalent, and they MUST contain identical values; their representation SHOULD also be identical. + * - A linear ring is the boundary of a surface or the boundary of a hole in a surface. + * - A linear ring MUST follow the right-hand rule with respect to the area it bounds, i.e., exterior rings are counterclockwise, and holes are clockwise. + * */ export interface GeoJsonPolygon extends GeoJsonObject { type: "Polygon"; + /** For type "Polygon", the "coordinates" member MUST be an array of linear ring coordinate arrays. */ coordinates: Position[][]; } -/** GeoJSON MultiPolygon */ +/** GeoJSON MultiPolygon. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.7) */ export interface GeoJsonMultiPolygon extends GeoJsonObject { type: "MultiPolygon"; + /** For type "MultiPolygon", the "coordinates" member is an array of Polygon coordinate arrays. */ coordinates: Position[][][]; } @@ -92,13 +109,18 @@ export type GeoJsonGeometry = | GeoJsonPolygon | GeoJsonMultiPolygon; -/** GeoJSON GeometryCollection */ +/** GeoJSON GeometryCollection. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.1.8) */ export interface GeoJsonGeometryCollection extends GeoJsonObject { type: "GeometryCollection"; - geometries: GeoJsonGeometry[] /* It's not recommended to include GeometryCollection recursively */; + /* It's not recommended to include GeometryCollection recursively */ + geometries: GeoJsonGeometry[]; } -/** GeoJSON Feature */ +/** + * GeoJSON Feature + * A Feature object represents a spatially bounded thing. Every Feature + object is a GeoJSON object. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) + */ export interface GeoJsonFeature extends GeoJsonObject { type: "Feature"; geometry?: GeoJsonGeometry; @@ -106,7 +128,7 @@ export interface GeoJsonFeature extends GeoJsonObject { id?: number | string; } -/** GeoJSON FeatureCollection */ +/** GeoJSON FeatureCollection. [Reference](https://www.rfc-editor.org/rfc/rfc7946#section-3.3) */ export interface GeoJsonFeatureCollection extends GeoJsonObject { type: "FeatureCollection"; features: GeoJsonFeature[];