@arcgis/core 5.2.0-next.13 → 5.2.0-next.14

package/geometry/Mesh.d.ts

@@ -37,7 +37,8 @@ export interface MeshProperties extends BaseGeometryProperties, LoadableMixinPro
    */
   components?: MeshComponentProperties[] | null;
   /**
-   * Additional local transformation of the mesh vertices. The transform is ignored if the [vertexSpace)(#vertexSpace)
+   * Additional local transformation of the mesh vertices. The transform is ignored if the
+   * [vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace)
    * is of type [georeferenced](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) and does not specify
    * an [MeshGeoreferencedVertexSpace.origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin).
    */
@@ -82,124 +83,228 @@ export interface MeshProperties extends BaseGeometryProperties, LoadableMixinPro
    * };
    */
   vertexAttributes?: MeshVertexAttributesProperties;
-  /** The vertex space of the mesh. See [mesh API](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#mesh-api) for details. */
+  /**
+   * Defines how the SDK interprets the x, y, z position values stored in
+   * [Mesh.vertexAttributes.position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position).
+   *
+   * A source 3D model or custom vertex buffer usually stores positions as numbers, but those numbers do not indicate by
+   * themselves whether they are local model coordinates, offsets from a placement point, or absolute map coordinates.
+   * This property makes that interpretation explicit for the Mesh geometry.
+   *
+   * Use [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) when the position values are meter-based local model coordinates
+   * and should be placed in a global [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). Use
+   * [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) when the position values should be interpreted as offsets or
+   * absolute coordinates in the coordinate system identified by
+   * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference), which is the usual choice for local scenes with a
+   * projected coordinate system.
+   *
+   * This property is construct-only because changing it changes the meaning of every vertex position in the mesh.
+   * To change the vertex space of an existing mesh, use [convertVertexSpace()](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/meshUtils/#convertVertexSpace).
+   */
   vertexSpace?: ((MeshGeoreferencedVertexSpaceProperties & { type: "georeferenced" }) | (MeshLocalVertexSpaceProperties & { type: "local" }));
 }
 
 /**
- * A mesh is a general, client-side 3D [Geometry](https://developers.arcgis.com/javascript/latest/references/core/geometry/Geometry/) type
- * composed of [vertices with attributes](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexAttributes). The vertices include
- * geographic position, normals that affect lighting/shading and UV coordinates that
- * can be used to map images to the mesh. Vertices are combined into 3D primitives
- * to render the mesh in the scene (only triangle primitives are currently supported).
- *
- * Mesh geometries can have an intrinsic material that determines how it is being
- * displayed. Similar to 3D objects in scene layers, mesh geometries are symbolized with a
- * [MeshSymbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/MeshSymbol3D/) symbol containing a
- * [FillSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/FillSymbol3DLayer/).
- *
- * To support multiple materials (as is often the case for complex 3D models), meshes
- * may define [components](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#components) that define a material for a specific region
- * in the mesh. In addition to supporting multiple materials, components can also
- * reuse vertices that would otherwise be duplicated to form triangles.
- *
- * Meshes are loadable since 4.27. In particular when meshes come from remote services like
- * through [SceneLayer.queryFeatures()](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#queryFeatures), then
- * the contents of the mesh needs to be loaded asynchronously through the
- * [load()](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#load) method before
- * [vertexAttributes](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexAttributes),
- * [extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#extent),
- * [components](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#components), etc. are available.
- *
- * Meshes represent fully georeferenced 3D geometry and care needs to be taken when importing mesh data.
+ * ## Overview
+ *
+ * In general 3D terminology, a mesh is a set of vertices connected into faces that define the shape and surface of a
+ * 3D object. In the Maps SDK, a Mesh instance is a [Geometry](https://developers.arcgis.com/javascript/latest/references/core/geometry/Geometry/) that stores those vertices in
+ * [vertexAttributes](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexAttributes).
+ *
+ * The [position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position) values define the shape of the 3D object,
+ * [normals](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#normal) affect lighting and shading, and
+ * [UV coordinates](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#uv) can be used to map images to the surface.
+ * [Mesh components](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshComponent/) define triangle faces and can assign materials to different
+ * regions of the Mesh geometry. Because faces index into the vertex attributes, components can reuse the same vertices
+ * instead of duplicating them for every triangle.
+ *
+ * Mesh geometries can define intrinsic materials. Similar to 3D objects in scene layers, they are symbolized with a
+ * [MeshSymbol3D](https://developers.arcgis.com/javascript/latest/references/core/symbols/MeshSymbol3D/) symbol containing a [FillSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/FillSymbol3DLayer/). The fill symbol layer renders
+ * the mesh surface and can define visual overrides such as material, color, and edges.
+ *
+ * Meshes returned from remote services, such as through [SceneLayer.queryFeatures()](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#queryFeatures), may need to load
+ * their content asynchronously. When a Mesh is added to a view through a [Graphic](https://developers.arcgis.com/javascript/latest/references/core/Graphic/), the API loads it as needed
+ * for display. Call [load()](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#load) before accessing properties such as
+ * [vertexAttributes](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexAttributes), [extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#extent), and [components](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#components) directly
+ * when the mesh is not yet loaded.
+ *
+ * ## Mesh georeferencing
+ *
+ * A source 3D model file, imported model, or custom vertex buffer often stores vertex positions as plain x, y, z
+ * numbers. Those numbers do not, by themselves, say whether [10, 0, 0] means ten meters east of the source model's
+ * own [0, 0, 0], ten map units east of a provided placement point in a projected coordinate system (PCS), or an absolute
+ * coordinate on a map. Some formats (e.g., IFC4) and workflows include georeferencing metadata, but a Mesh instance still needs
+ * an explicit interpretation of the position values stored in [MeshVertexAttributes.position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position).
+ *
+ * The [vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) property provides this interpretation. It specifies whether
+ * the position values are coordinates relative to the model's own origin, offsets from an specific origin you provide,
+ * or absolute map coordinates.
+ *
+ * To georeference a Mesh geometry:
+ *
+ * 1. Note the [SceneView.viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) you are using. A "global" scene and a
+ *    "local" scene require different Mesh configurations to work correctly and efficiently.
+ * 2. Set [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) to a coordinate system compatible with that
+ *    [viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode).
+ * 3. Choose [Mesh.vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) based on both the
+ *    [viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) and what the source x, y, z values mean.
+ * 4. Provide an origin only when the source x, y, z values are offsets from a placement point, such as the source model's
+ *    own [0, 0, 0] or an insertion point. The origin is stored on the selected vertex space:
+ *    [local](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/#origin) or
+ *    [georeferenced](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin).
+ *
+ * ### Common georeferencing workflows
+ *
+ * The common workflows below show how to choose a vertex space for source values that are measured from [0, 0, 0],
+ * offsets from a placement point, or absolute map coordinates.
+ *
+ * - In a [global](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) view, use [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/).
+ *   This is common for models whose x, y, z positions describe the object relative to the model's own [0, 0, 0],
+ *   such as models from 3D modeling or CAD tools. Set [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference)
+ *   to a geographic coordinate system, such as WGS84 or CGCS2000, or to Web Mercator, and set
+ *   [MeshLocalVertexSpace.origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/#origin) to the coordinate where the model's [0, 0, 0] should land.
+ * - In a [local](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) view, use [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) with
+ *   an [MeshGeoreferencedVertexSpace.origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin). This works for both source data whose x, y, z
+ *   values are offsets from a placement point, and for models whose x, y, z positions describe the object relative to
+ *   the model's own [0, 0, 0]. Set [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) to the same projected
+ *   coordinate system as [SceneView.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#spatialReference). The SDK then treats each x, y, z position as an
+ *   offset from the origin in the projected coordinate system used by the view.
+ * - To use source data whose x, y, z positions were already exported as coordinates in a projected coordinate system,
+ *   use [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) without an origin. Set
+ *   [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) to that projected coordinate system. Each x, y, z
+ *   position is then interpreted as an absolute coordinate in that coordinate system.
+ * - When you create primitives or import glTF with [meshUtils](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/meshUtils/) create functions and do not
+ *   provide a vertex space, the SDK chooses one from the provided location. It chooses
+ *   [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) when the location's spatial reference is geographic, such as WGS84
+ *   or CGCS2000, or when it is Web Mercator. It chooses [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) for
+ *   other projected coordinate systems. This is a helper default; choose the vertex space explicitly when your view
+ *   setup or data workflow requires a different interpretation.
+ *
  * <details>
  * <summary>Read More</summary>
  *
- * It is typical for modern 3D GIS workflows that 3D geometry data be represented by 3D models, which can be stored in different file formats like glTF, OBJ, FBX, IFC, etc. These models can come from different sources, such as 3D modeling software like SketchUp or Blender, CAD software like Revit, or even custom mesh generation code.
- *
- * While some of the software may work in a georeferenced space and some of the file formats, such as IFC, may be georeferenced, much of the software and most of the model file formats are not georeferenced. This presents the challenge of expressing different georeferencing scenarios while maintaining a fast and efficient experience when displaying and editing 3D model content. In the Maps SDK we strive to strike a good balance between allowing our users to work with different scenarios while preventing situations in which good display and editing experience cannot be provided.
- *
  * <span id="mesh-api"></span>
- * ## Mesh API
- *
- * The entry point for representing 3D models in the Maps SDK is the [Mesh](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/). We refer to the API reference for details on mesh [components](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#components), [MeshComponent.material](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshComponent/#material) and how to create meshes. This guide is concerned with georeferencing meshes.
- *
- * A mesh represents a georeferenced 3D model in the Maps SDK. In order to fully georeference meshes three things are needed:
- * 1. Spatial reference
- * 2. Location of the mesh in that spatial reference. We call this the origin.
- * 3. The coordinate system in which mesh vertices are provided. We call it the vertex space.
- *
- * Given these three things, meshes can be fully georeferenced. However, for certain configurations of spatial reference, mesh vertex space and viewing mode, costly projection may be required. Because that would greatly affect display and editing performance, we decided to not display or allow editing in those cases. Please see the [limitations](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#limitations) section for an overview of these restrictions.
- *
- * The [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/geometry/SpatialReference/) of the mesh is provided with its construction. When using one of the create functions, such as
- * [createFromGLTF()](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#createFromGLTF), the spatial reference will be taken from the provided location.
  *
- * ### Mesh vertex spaces
+ * ### Local vertex space
  *
- * The origin and spatial reference of a mesh provide georeferencing, but only for the origin. A mesh is composed of vertices, and they may exist in different coordinate systems depending on the data source. Hence, to fully georeference the mesh, it's crucial to define the coordinate system associated with the mesh vertices. The [mesh vertex space property](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) was introduced to address this need. This property specifies the meaning of the mesh vertex coordinates, ensuring that the entire mesh can be correctly georeferenced.
- *
- * #### Mesh local vertex space
- *
- * Most popular 3D model formats, such as glTF, are not georeferenced and represent the mesh vertex coordinates in a plain **local cartesian** space with some length unit (e.g. `meters` for glTF). The coordinate (0,0,0) is the origin. We call this coordinate system "local" and represent it using the [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/). The units in this vertex space are always "meters".
+ * In a [local vertex space](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/), the
+ * [MeshVertexAttributes.position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position) values are model coordinates in meters, measured from the
+ * source model's local [0, 0, 0]. The [MeshLocalVertexSpace.origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/#origin) places that local origin
+ * at an [x, y, z] coordinate in the coordinate system identified by
+ * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
  *
  * <img src="https://developers.arcgis.com/javascript/latest/assets/references/core/geometry/mesh-local-vertex-space.avif" style="width:300px;"/>
  *
  * *local vertex space*
  *
- * Georeferencing local coordinates is done by "putting them on the map" using a georeferenced cartesian reference frame. This frame is found by using the [local tangent plane](https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates) at the georeferenced origin of the mesh. When the spatial reference uses a geographic coordinate system (GCS) or Web Mercator, the tangent plane is aligned such that the local Y tangent vector is always pointing to the north pole resulting in the east, north, up (ENU) frame.
- *
- * Currently we use the tangent plane of the sphere even for ellipsoidal geographic coordinate systems. This is a simplification we use as we render on a perfect sphere in global viewing mode.
+ * When a Mesh geometry with [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) is displayed in a global scene and
+ * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) is WGS84, CGCS2000, or Web Mercator, the SDK places the
+ * local coordinate frame on the globe at [MeshLocalVertexSpace.origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/#origin). The frame is aligned to
+ * the [local tangent plane](https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates): X points east, Y points
+ * north, and Z points up. This is commonly called an east, north, up (ENU) frame.
  *
  * <img src="https://developers.arcgis.com/javascript/latest/assets/references/core/geometry/mesh-local-vertex-space-on-GCS-or-WM.avif" style="width:300px;"/>
  *
- * *local vertex space on GCS or Web Mercator (ENU)*
- *
- * A [local vertex space](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) with a spatial reference which is a GCS or Web Mercator is efficient to work with as the tangent plane is easy to find and we can simply move the vertices to its georeferenced location using efficient linear transformations. This comes at the cost of an approximation error between the tangent plane and the actual surface. Consequently for larger models, this error increases while it decreases as the models get smaller.
- *
- * There is an important element to consider when a mesh is created with a [local vertex space](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) (e.g. by creating it from a glTF) and displayed in local viewing mode where a projected coordinate system (PCS) is used:
- *
- * The projection introduces a warping and distortion of the space in order to allow mapping of surface coordinates to a plane. This produces a mismatch between the linear coordinates of the local vertex space and the warped, non-linear coordinates of the underlying spatial reference. While steps along a line in the local vertex space are of same length, steps along a line in the underlying spatial reference are not. This means that measuring the same line in local space and the underlying spatial reference will produce different measurements. This difference further depends on the origin location of the mesh. It is important to realize that this scenario cannot be used when correct georeferencing is required.
- *
- * #### Mesh georeferenced vertex spaces
- *
- * The [georeferenced vertex space](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) indicates that mesh vertices are already projected and that their coordinates are in the spatial reference of the mesh. If an [MeshGeoreferencedVertexSpace.origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin) is provided, those vertex coordinates are interpreted as offsets relative to the origin. Otherwise, the coordinates are interpreted as absolute.
+ * *local vertex space aligned to the sphere's tangent plane at the origin point*
+ *
+ * This reference-frame approach is an approximation: it uses a spherical tangent plane matching how global scenes
+ * are rendered. The farther a vertex is from
+ * [MeshLocalVertexSpace.origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/#origin), the more the local tangent plane diverges from the curved
+ * surface. This is usually acceptable for buildings and other models that occupy a limited area, but it is not
+ * appropriate for long objects that must follow the earth's curvature.
+ *
+ * The word "local" in [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) refers to coordinates from the source model
+ * measured from that model's own [0, 0, 0]. It does not mean that this vertex space is the right choice for a
+ * [local](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) view. For mesh graphics in a local view, use
+ * [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) in the view's projected coordinate system.
+ *
+ * ### Georeferenced vertex space
+ *
+ * [Mesh.vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) gives meaning to the source x, y, z values stored in
+ * [MeshVertexAttributes.position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position). A
+ * [georeferenced vertex space](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) interprets those numbers in relation
+ * to [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference), either as offsets from a placement point or as
+ * absolute map coordinates.
+ *
+ * - When the [origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin) is set, the mesh's vertex coordinates
+ *   are interpreted as offsets from that origin. This works well for 3D models created by CAD software whose x, y and z
+ *   values are measured from the source model's own [0, 0, 0], and for those measured from a specific insertion point.
+ *   The origin is the [x, y, z] coordinate, in the Mesh's
+ *   [spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference), where that local [0, 0, 0] or insertion point lands.
+ *   The offset directions and units come from [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference). In a
+ *   projected coordinate system, these are usually map units such as meters.
+ * - Without an [origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin), use this vertex space
+ *   when the source x, y, z values are already absolute map coordinates, for example a mesh produced from a LiDAR scan,
+ *   photogrammetry reconstruction, or surveyed surface and exported in a projected coordinate system. Each source
+ *   position is used directly in [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
  *
  * <img src="https://developers.arcgis.com/javascript/latest/assets/references/core/geometry/mesh-georeferenced-vertex-space-on-PCS.avif" style="width:300px;"/>
  *
- * *georeferenced vertex space on PCS*
- *
- * Display and editing are efficient for meshes with a georeferenced vertex space and when the spatial reference is a projected coordinate system and matches the spatial reference of the view. This is because in those cases, manipulations like moving a mesh can be expressed as linear transformations.
- *
- * ## The effect of viewing modes
- *
- * We will not display or allow edits for configurations where efficient display or editing is not possible due to costly reprojections being required. It is important to realize that the [SceneView.viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) defines the spatial reference in which the data is displayed and hence has a direct effect on which vertex space and spatial reference combination of meshes can be done efficiently. This means that, depending on the viewing mode, display and editing of meshes with certain combinations of vertex space and spatial reference are not supported. See [limitations](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#limitations) for an overview.
- *
- * We established that for mesh spatial references which use a geographic coordinate system (or Web Mercator) and a local vertex space, display and editing can be done efficiently. That is true for `"global"` viewing mode, where the view uses a geographic coordinate system (or Web Mercator) for display.
- *
- * Meshes with a georeferenced vertex space and a spatial reference using a projected coordinate system (PCS) can be displayed and edited efficiently in a view using the `"local"` viewing mode and when the view has the same spatial reference as the mesh.
- *
- * ## Web Mercator
- *
- * Web Mercator is a spatial reference with a projected coordinate system and the de facto standard for web mapping applications. This is due to its suitability for efficient map tiling. Even though it uses a projected coordinate system, we still support using Web Mercator in global viewing mode. This is because of its importance for web mapping and also because projecting Web Mercator on the globe cancels out the strong distortions near the poles. It is the only PCS based spatial reference we support in global viewing mode.
- *
- * Web Mercator support for global viewing mode naturally extends to supporting efficient display and editing for meshes with a Web Mercator spatial reference and a local vertex space, even though it is based on a projected coordinate system. Since Web Mercator is a spatial reference based on a PCS, we also support efficient display and editing for Web Mercator with meshes using a georeferenced vertex space. Web Mercator is the only exception to the rule of only meshes with a spatial reference with a geographic coordinate system can be supported in global viewing mode.
+ * *georeferenced vertex space on a projected coordinate system*
+ *
+ * A georeferenced vertex space is the usual choice for mesh graphics in local scenes. Use it when the
+ * [view spatial reference](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#spatialReference) is a projected coordinate system and
+ * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) uses the same projected coordinate system. In that
+ * configuration, the position values and the view use the same projected coordinate space, so display and editing can
+ * be efficient and predictable.
+ *
+ * > [!WARNING]
+ * > Do not use a georeferenced vertex space with a
+ * > [vertex space origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin) in WGS84 or CGCS2000 for source
+ * > models whose x, y, z values are measured in meters. In those geographic coordinate systems, longitude and latitude
+ * > are angular coordinates, so an offset such as [10, 0, 0] means ten degrees of longitude, not ten meters east.
+ * > A building model can appear at the wrong size or far from the intended location. If the source model is measured in
+ * > meters and should be placed on the globe, use [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) instead.
+ *
+ * ### Web Mercator
+ *
+ * Web Mercator is a projected coordinate system, but it is treated specially in global scenes because of its central
+ * role in web mapping. A Mesh geometry whose [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) is Web
+ * Mercator can use
+ * [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) in a global [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). Other projected coordinate
+ * systems should use a local [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/) and [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/).
+ *
+ * Web Mercator is not recommended as the spatial reference for local scenes or for publishing 3D object layers that
+ * require accurate local dimensions. Web Mercator map units are distorted: one Web Mercator meter equals one ground
+ * meter only near the equator, and the scale variation increases with latitude. For local scenes and 3D object layer
+ * workflows, prefer a projected coordinate system designed for the area of interest.
+ *
+ * ### Troubleshooting mesh georeferencing
+ *
+ * If a mesh graphic is not displayed, or is displayed in the wrong place or at the wrong size, first check the browser
+ * console for warnings. Then narrow the problem in this order:
+ *
+ * 1. Start with [SceneView.viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode). In a global SceneView, the usual choice for model files whose
+ *    positions are measured from the model's own [0, 0, 0] is [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/). In a
+ *    local SceneView, the usual choice is [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) with a projected
+ *    [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) that matches
+ *    [SceneView.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#spatialReference).
+ * 2. Identify what the source model's x, y, z values mean. They may be local model coordinates measured from
+ *    [0, 0, 0], offsets from an insertion point, or absolute coordinates exported by a georeferenced workflow.
+ * 3. Check the vertex space's origin when it has one. The origin should be the [x, y, z] coordinate where the source
+ *    model's [0, 0, 0] or insertion point should land, using the coordinate system identified by
+ *    [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
+ * 4. Check units. [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) interprets position values as meters.
+ *    [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) with a vertex space origin interprets offsets in the units
+ *    of [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
  *
  * <span id="limitations"></span>
- * ## Limitations
- *
- * - See [Scene Layers](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) in regards to limitations on display and editing for mesh features.
- *
- * ## Troubleshooting mesh georeferencing
- *
- * If meshes are not being displayed, then chances are that this is due to a configuration which the API does not support for display and editing.
- *
- * - First check the [SceneView.viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode), [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) and [vertex space](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) of the problematic mesh and consult the console of the JavaScript debugger. If the API rejects display of meshes, a warning message is printed.
- * - If it is determined that an unsupported configuration is used, consider switching the [SceneView.viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) in your application.
- * - If there is no other option, consider changing the data by switching to a supported spatial reference for the required [SceneView.viewingMode](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) or by converting the mesh vertex data between local and georeferenced vertex space.
- * - If meshes are displayed wrongly, then this could also be due to the vertex space not being correct. If applications export geometry with georeferenced coordinates as OBJ file for example, then one would need to use the `"georeferenced"` vertex space.
+ * ### Limitations
+ *
+ * - [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) is not supported for mesh graphics displayed in a local
+ *   [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
+ * - Displaying or editing a Mesh geometry can be unsupported when
+ *   [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference),
+ *   [SceneView.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#spatialReference), and
+ *   [Mesh.vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) would require costly or unavailable per-vertex projection.
+ * - For 3D object feature editing workflows that use Mesh geometry, see the
+ *   [SceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) editing documentation and
+ *   [3D object workflows in the SDK](https://developers.arcgis.com/javascript/latest/3d-object-workflows/#essential-aspects-of-the-editing-workflow).
  *
  * </details>
  *
+ * ---
+ *
  * ## Create simple mesh geometry primitives
  *
  * There are a couple of convenience functions in [meshUtils](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/meshUtils/) to create simple
@@ -231,6 +336,8 @@ export interface MeshProperties extends BaseGeometryProperties, LoadableMixinPro
  * view.graphics.add(graphic);
  * ```
  *
+ * ---
+ *
  * ## Create mesh geometries manually
  *
  * Mesh geometries can be manually created by specifying [vertexAttributes](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexAttributes) and
@@ -445,7 +552,8 @@ export default class Mesh extends MeshSuperclass {
    */
   get origin(): Point;
   /**
-   * Additional local transformation of the mesh vertices. The transform is ignored if the [vertexSpace)(#vertexSpace)
+   * Additional local transformation of the mesh vertices. The transform is ignored if the
+   * [vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace)
    * is of type [georeferenced](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) and does not specify
    * an [MeshGeoreferencedVertexSpace.origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin).
    */
@@ -494,7 +602,24 @@ export default class Mesh extends MeshSuperclass {
    */
   get vertexAttributes(): MeshVertexAttributes;
   set vertexAttributes(value: MeshVertexAttributesProperties);
-  /** The vertex space of the mesh. See [mesh API](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#mesh-api) for details. */
+  /**
+   * Defines how the SDK interprets the x, y, z position values stored in
+   * [Mesh.vertexAttributes.position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position).
+   *
+   * A source 3D model or custom vertex buffer usually stores positions as numbers, but those numbers do not indicate by
+   * themselves whether they are local model coordinates, offsets from a placement point, or absolute map coordinates.
+   * This property makes that interpretation explicit for the Mesh geometry.
+   *
+   * Use [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/) when the position values are meter-based local model coordinates
+   * and should be placed in a global [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). Use
+   * [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) when the position values should be interpreted as offsets or
+   * absolute coordinates in the coordinate system identified by
+   * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference), which is the usual choice for local scenes with a
+   * projected coordinate system.
+   *
+   * This property is construct-only because changing it changes the meaning of every vertex position in the mesh.
+   * To change the vertex space of an existing mesh, use [convertVertexSpace()](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/meshUtils/#convertVertexSpace).
+   */
   get vertexSpace(): MeshVertexSpaceUnion;
   /**
    * Adds a component to the mesh.

package/geometry/operators/support/projectionZScaling.js

@@ -1,2 +1,2 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
-import t from"../../../core/Error.js";import{isGeometryWithZ as o,getJsonType as r}from"../../support/jsonTypeUtils.js";import{getGeometryZScaler as e}from"../../support/zscale.js";function s(t,s,n){let p;for(const c of t)if(c&&o(c)&&!("vertexAttributes"in c)){if(!p){null==s.vcsWkid&&null==n.vcsWkid||i(s,n);const t="type"in c?c.type:r(c);if(p=e(t,s,n),!p)return}p(c)}}class n extends t{constructor(){super("projection:z-unsupported","projection of z values is unsupported between different vertical coordinate systems")}}function i({vcsWkid:t},{vcsWkid:o}){if((t??null)!==(o??null))throw new n}export{n as ProjectZUnsupportedError,s as applyZConversionAfterProjection,i as validateVCSForZConversion};
+import{isGeometryWithZ as t,getJsonType as o}from"../../support/jsonTypeUtils.js";import{getGeometryZScaler as r}from"../../support/zscale.js";function e(e,i,p){let s;for(const f of e)if(f&&t(f)&&!("vertexAttributes"in f)){if(!s){const t="type"in f?f.type:o(f);if(s=r(t,i,p),!s)return}s(f)}}export{e as applyZConversionAfterProjection};

package/geometry/support/MeshGeoreferencedVertexSpace.d.ts

@@ -4,27 +4,49 @@ import type { JSONSupport } from "../../core/JSONSupport.js";
 export interface MeshGeoreferencedVertexSpaceProperties extends Partial<Pick<MeshGeoreferencedVertexSpace, "origin">> {}
 
 /**
- * A mesh vertex space indicating that mesh vertices are either absolute georeferenced map coordinates or relative
- * offsets in map space to a fully georeferenced
- * origin. The map space is identified by the [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) of
- * the mesh.
+ * Represents a [vertex space](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) that interprets
+ * [Mesh vertex positions](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position) in relation to
+ * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
  *
- * The vertex space of a mesh allows users to specify how the coordinates of the mesh vertices are interpreted. Use the
- * georeferenced vertex space if the coordinates are already in the spatial reference of the mesh. The coordinates can
- * be relative to the [origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin) or absolute
- * coordinates if the origin is not defined.
+ * A vertex space is the [Mesh.vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) object that tells the SDK how to read the
+ * x, y, z positions stored in [Mesh.vertexAttributes.position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position).
+ * Use MeshGeoreferencedVertexSpace when those source numbers should be interpreted in map space, either as offsets
+ * from a placement point or as absolute coordinates in [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
  *
- * See [mesh API](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#mesh-api) for more details.
+ * This vertex space has two common workflows:
+ *
+ * - In a local [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/) with a projected coordinate system, use a
+ *   [vertex space origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin) for models from 3D modeling or CAD
+ *   tools, whose positions are measured from the source model's own [0,0,0], or for data measured from an insertion
+ *   point. The vertex space origin places that local [0,0,0] or insertion point in
+ *   [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference). Each source position is then an offset from the
+ *   vertex space origin, using the units and directions of
+ *   [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
+ * - For source data already exported with absolute coordinates, use no vertex space origin. Each source position is
+ *   already an absolute x, y, z location in [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
+ *
+ * Use the same projected coordinate system for [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) and
+ * [SceneView.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#spatialReference) when displaying or editing mesh graphics in a
+ * local scene. Do not use this vertex space with a
+ * [vertex space origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/#origin) in WGS84 or CGCS2000 for
+ * meter-based model coordinates: longitude and latitude are angular units, so [10, 0, 0] is not ten meters east.
  *
  * @since 4.27
- * @see [Mesh](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/)
+ * @see [Mesh.vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace)
+ * @see [MeshLocalVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/)
  */
 export default class MeshGeoreferencedVertexSpace extends MeshGeoreferencedVertexSpaceSuperclass {
   constructor(properties?: MeshGeoreferencedVertexSpaceProperties);
   /**
-   * Origin of the vertex space. These coordinates are interpreted in the spatial reference of the mesh using the vertex space.
-   * If this is null, the coordinates are expected to be absolute. If not, the coordinates are expected to be deltas relative
-   * to the origin.
+   * Optional coordinate used to place source position values that are offsets.
+   *
+   * With a vertex space origin, this [x, y, z] coordinate is interpreted in
+   * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference). Each source position in
+   * [Mesh.vertexAttributes.position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position) is then an offset from the
+   * vertex space's origin.
+   *
+   * Without a vertex space origin, each source position is already an absolute x, y, z location in
+   * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
    */
   accessor origin: readonly [
       number,

package/geometry/support/MeshLocalVertexSpace.d.ts

@@ -4,20 +4,44 @@ import type { JSONSupport } from "../../core/JSONSupport.js";
 export interface MeshLocalVertexSpaceProperties extends Partial<Pick<MeshLocalVertexSpace, "origin">> {}
 
 /**
- * A mesh vertex space that indicates mesh vertices exist in a plain cartesian space as often encountered in 3D
- * modeling and CAD applications. Georeferencing is done by using the coordinates in the
- * [local tangent plane](https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates)
- * reference frame at the fully georeferenced [origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/#origin)
- * of the vertex space.
+ * Represents a [vertex space](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) that interprets
+ * [Mesh vertex positions](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position) as x, y, z values measured in meters
+ * from the source model's own [0,0,0].
  *
- * See [mesh API](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#mesh-api) for details.
+ * A vertex space is the [Mesh.vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) object that tells the SDK how to read the
+ * x, y, z positions stored in [Mesh.vertexAttributes.position](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshVertexAttributes/#position).
+ * Use MeshLocalVertexSpace when those positions describe the shape of a source model relative to the model's own
+ * [0,0,0], and you want to place that model in a global [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
+ *
+ * The [vertex space's origin](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshLocalVertexSpace/#origin) is the [x, y, z] coordinate where the
+ * source model's [0,0,0] lands. The origin values use the coordinate system identified by
+ * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference). For example, with WGS84 the origin contains longitude,
+ * latitude, and elevation values; with Web Mercator it contains Web Mercator x, y, and z values.
+ *
+ * In a global scene with WGS84, CGCS2000, or Web Mercator, the SDK places the model on a
+ * [local tangent plane](https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates) at the origin. The x-axis points
+ * east, the y-axis points north, and the z-axis points up.
+ *
+ * The word local refers to local coordinates from the source model. It does not mean this vertex space is used for
+ * a [local](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#viewingMode) SceneView. For local scenes, use
+ * [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/) and a
+ * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) that matches
+ * [SceneView.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#spatialReference).
  *
  * @since 4.27
- * @see [Mesh](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/)
+ * @see [Mesh.vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace)
+ * @see [MeshGeoreferencedVertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/support/MeshGeoreferencedVertexSpace/)
  */
 export default class MeshLocalVertexSpace extends MeshLocalVertexSpaceSuperclass {
   constructor(properties?: MeshLocalVertexSpaceProperties);
-  /** Origin of the vertex space. These coordinates are interpreted in the spatial reference of the mesh using the vertex space. */
+  /**
+   * Coordinates of the place where the source model's local [0,0,0] is anchored.
+   *
+   * The array is [x, y, z] in the coordinate system identified by the
+   * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference) property of the Mesh geometry that uses this vertex
+   * space. The vertex position [0,0,0] coincides with the vertex space's origin before any
+   * [Mesh.transform](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#transform) is applied.
+   */
   accessor origin: readonly [
       number,
       number,

package/geometry/support/MeshVertexAttributes.d.ts

@@ -19,8 +19,12 @@ export default class MeshVertexAttributes extends MeshVertexAttributesSuperclass
    */
   accessor normal: MeshVertexNormal | null | undefined;
   /**
-   * A flat array of vertex positions. Vertex positions have x, y and z coordinates and they should be in the spatial
-   * reference system of the geometry.
+   * A flat array of vertex position values.
+   *
+   * Every three numbers define one x, y, z position. The [Mesh.vertexSpace](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#vertexSpace) property
+   * of the `Mesh` geometry that owns these attributes defines how the SDK interprets those numbers: as local model
+   * coordinates, as offsets from an origin, or as absolute coordinates in the coordinate system identified by
+   * [Mesh.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#spatialReference).
    *
    * @since 5.0
    */

package/geometry/support/heightModelInfoUtils.js

@@ -1,2 +1,2 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
-import e from"../../core/Error.js";import t from"../HeightModelInfo.js";import{parse as n}from"../../layers/support/arcgisLayerUrl.js";function i(n,i){if(!n)return null;if(!o(n))return new e("webscene:unsupported-height-model-info","The vertical coordinate system of the scene is not supported",{heightModelInfo:n});const a=n.heightUnit,r=t.deriveUnitFromSR(n,i).heightUnit;return a!==r?new e("webscene:incompatible-height-unit",`The vertical units of the scene (${a}) must match the horizontal units of the scene (${r})`,{verticalUnit:a,horizontalUnit:r}):null}function a(n,i,a){const o=c(n),l=i,h=r(o,l,a);if(o){const i=t.deriveUnitFromSR(o,n.spatialReference).heightUnit;if(!a&&i!==o.heightUnit){const t=new e("layerview:unmatched-height-unit",`The vertical units of the layer must match the horizontal units (${i})`,{horizontalUnit:i});return new e("layerview:unsupported-height-model-info","The vertical coordinate system of the layer is not supported",{heightModelInfo:o,error:t})}}if(!s(n)||4===h)return new e("layerview:unsupported-height-model-info","The vertical coordinate system of the layer is not supported",{heightModelInfo:o});switch(h){case 1:{const t=o?.heightUnit||"unknown",n=l?.heightUnit||"unknown",i=new e("layerview:incompatible-height-unit",`The vertical units of the layer (${t}) must match the vertical units of the scene (${n})`,{layerUnit:t,sceneUnit:n});return new e("layerview:incompatible-height-model-info","The vertical coordinate system of the layer is incompatible with the scene",{layerHeightModelInfo:o,sceneHeightModelInfo:l,error:i})}case 2:{const t=o?.heightModel||"unknown",n=l?.heightModel||"unknown",i=new e("layerview:incompatible-height-model",`The height model of the layer (${t}) must match the height model of the scene (${n})`,{layerHeightModel:t,sceneHeightModel:n});return new e("layerview:incompatible-height-model-info","The vertical coordinate system of the layer is incompatible with the scene",{layerHeightModelInfo:o,sceneHeightModelInfo:l,error:i})}case 3:{const t=o?.vertCRS||"unknown",n=l?.vertCRS||"unknown",i=new e("layerview:incompatible-vertical-datum",`The vertical datum of the layer (${t}) must match the vertical datum of the scene (${n})`,{layerDatum:t,sceneDatum:n});return new e("layerview:incompatible-height-model-info","The vertical coordinate system of the layer is incompatible with the scene",{layerHeightModelInfo:o,sceneHeightModelInfo:l,error:i})}}return null}function r(e,t,n){if(!o(e)||!o(t))return 4;if(null==e||null==t)return 0;if(!n&&e.heightUnit!==t.heightUnit)return 1;if(e.heightModel!==t.heightModel)return 2;switch(e.heightModel){case"gravity-related-height":return 0;case"ellipsoidal":return e.vertCRS===t.vertCRS?0:3;default:return 4}}function o(e){return null==e||null!=e.heightModel&&null!=e.heightUnit}function s(e){return"heightModelInfo"in e&&null!=e.heightModelInfo||null!=e.spatialReference||!u(e)}function c(e){if("integrated-mesh-3dtiles"===e.type||"gaussian-splat"===e.type)return null;const i=e.url?n(e.url):void 0,a=e.spatialReference?.vcsWkid;return!(null==a&&null!=i&&"ImageServer"===i.serverType)&&l(e)&&e.heightModelInfo?e.heightModelInfo:u(e)?t.deriveUnitFromSR(f,e.spatialReference):null}function l(e){return"heightModelInfo"in e}function h(e){if("unknown"===e.type||!("capabilities"in e))return!1;switch(e.type){case"annotation":case"catalog":case"catalog-footprint":case"csv":case"feature":case"dimension-feature":case"geojson":case"subtype-group":case"ogc-feature":case"oriented-imagery":case"wfs":case"knowledge-graph-sublayer":return!0;default:return!1}}function u(e){return h(e)?!!(e.capabilities&&e.capabilities.data&&e.capabilities.data.supportsZ):d(e)}function g(e){return null!=e.layers||d(e)||h(e)||l(e)}function d(e){switch(e.type){case"annotation":case"building-scene":case"elevation":case"gaussian-splat":case"integrated-mesh":case"integrated-mesh-3dtiles":case"point-cloud":case"scene":case"voxel":return!0;case"base-dynamic":case"base-elevation":case"base-tile":case"bing-maps":case"catalog":case"catalog-footprint":case"catalog-dynamic-group":case"csv":case"dimension":case"dimension-feature":case"geojson":case"feature":case"subtype-group":case"geo-rss":case"graphics":case"group":case"imagery":case"imagery-tile":case"kml":case"knowledge-graph":case"link-chart":case"knowledge-graph-sublayer":case"line-of-sight":case"map-image":case"map-notes":case"media":case"ogc-feature":case"open-street-map":case"oriented-imagery":case"parquet":case"route":case"stream":case"tile":case"unknown":case"unsupported":case"vector-tile":case"video":case"viewshed":case"wcs":case"web-tile":case"wfs":case"wms":case"wmts":case null:return!1}return!1}const f=new t({heightModel:"gravity-related-height"});export{c as deriveHeightModelInfoFromLayer,r as isCompatible,a as rejectLayerError,g as supportsHeightModelInfo,i as validateWebSceneError};
+import e from"../../core/Error.js";import t from"../HeightModelInfo.js";import{parse as n}from"../../layers/support/arcgisLayerUrl.js";function i(n,i){if(!n)return null;if(!o(n))return new e("webscene:unsupported-height-model-info","The vertical coordinate system of the scene is not supported",{heightModelInfo:n});const a=n.heightUnit,r=t.deriveUnitFromSR(n,i).heightUnit;return a!==r?new e("webscene:incompatible-height-unit",`The vertical units of the scene (${a}) must match the horizontal units of the scene (${r})`,{verticalUnit:a,horizontalUnit:r}):null}function a(n,i,a){const o=c(n),l=i,h=r(o,l,a);if(o){const i=t.deriveUnitFromSR(o,n.spatialReference).heightUnit;if(!a&&i!==o.heightUnit){const t=new e("layerview:unmatched-height-unit",`The vertical units of the layer must match the horizontal units (${i})`,{horizontalUnit:i});return new e("layerview:unsupported-height-model-info","The vertical coordinate system of the layer is not supported",{heightModelInfo:o,error:t})}}if(!s(n)||4===h)return new e("layerview:unsupported-height-model-info","The vertical coordinate system of the layer is not supported",{heightModelInfo:o});switch(h){case 1:{const t=o?.heightUnit||"unknown",n=l?.heightUnit||"unknown",i=new e("layerview:incompatible-height-unit",`The vertical units of the layer (${t}) must match the vertical units of the scene (${n})`,{layerUnit:t,sceneUnit:n});return new e("layerview:incompatible-height-model-info","The vertical coordinate system of the layer is incompatible with the scene",{layerHeightModelInfo:o,sceneHeightModelInfo:l,error:i})}case 2:{const t=o?.heightModel||"unknown",n=l?.heightModel||"unknown",i=new e("layerview:incompatible-height-model",`The height model of the layer (${t}) must match the height model of the scene (${n})`,{layerHeightModel:t,sceneHeightModel:n});return new e("layerview:incompatible-height-model-info","The vertical coordinate system of the layer is incompatible with the scene",{layerHeightModelInfo:o,sceneHeightModelInfo:l,error:i})}case 3:{const t=o?.vertCRS||"unknown",n=l?.vertCRS||"unknown",i=new e("layerview:incompatible-vertical-datum",`The vertical datum of the layer (${t}) must match the vertical datum of the scene (${n})`,{layerDatum:t,sceneDatum:n});return new e("layerview:incompatible-height-model-info","The vertical coordinate system of the layer is incompatible with the scene",{layerHeightModelInfo:o,sceneHeightModelInfo:l,error:i})}}return null}function r(e,t,n){if(!o(e)||!o(t))return 4;if(null==e||null==t)return 0;if(!n&&e.heightUnit!==t.heightUnit)return 1;if(e.heightModel!==t.heightModel)return 2;switch(e.heightModel){case"gravity-related-height":return 0;case"ellipsoidal":return e.vertCRS===t.vertCRS?0:3;default:return 4}}function o(e){return null==e||null!=e.heightModel&&null!=e.heightUnit}function s(e){return"heightModelInfo"in e&&null!=e.heightModelInfo||null!=e.spatialReference||!u(e)}function c(e){if("integrated-mesh-3dtiles"===e.type||"gaussian-splat"===e.type)return null;const i=e.url?n(e.url):void 0,a=e.spatialReference?.vcsWkid;return!(null==a&&null!=i&&"ImageServer"===i.serverType)&&l(e)&&e.heightModelInfo?e.heightModelInfo:u(e)?t.deriveUnitFromSR(f,e.spatialReference):null}function l(e){return"heightModelInfo"in e}function h(e){if("unknown"===e.type||!("capabilities"in e))return!1;switch(e.type){case"annotation-feature":case"catalog":case"catalog-footprint":case"csv":case"feature":case"dimension-feature":case"geojson":case"subtype-group":case"ogc-feature":case"oriented-imagery":case"wfs":case"knowledge-graph-sublayer":return!0;default:return!1}}function u(e){return h(e)?!!(e.capabilities&&e.capabilities.data&&e.capabilities.data.supportsZ):d(e)}function g(e){return null!=e.layers||d(e)||h(e)||l(e)}function d(e){switch(e.type){case"annotation-feature":case"building-scene":case"elevation":case"gaussian-splat":case"integrated-mesh":case"integrated-mesh-3dtiles":case"point-cloud":case"scene":case"voxel":return!0;case"base-dynamic":case"base-elevation":case"base-tile":case"bing-maps":case"catalog":case"catalog-footprint":case"catalog-dynamic-group":case"csv":case"dimension":case"dimension-feature":case"geojson":case"feature":case"subtype-group":case"geo-rss":case"graphics":case"group":case"imagery":case"imagery-tile":case"kml":case"knowledge-graph":case"link-chart":case"knowledge-graph-sublayer":case"line-of-sight":case"map-image":case"map-notes":case"media":case"ogc-feature":case"open-street-map":case"oriented-imagery":case"parquet":case"route":case"stream":case"tile":case"unknown":case"unsupported":case"vector-tile":case"video":case"viewshed":case"wcs":case"web-tile":case"wfs":case"wms":case"wmts":case null:return!1}return!1}const f=new t({heightModel:"gravity-related-height"});export{c as deriveHeightModelInfoFromLayer,r as isCompatible,a as rejectLayerError,g as supportsHeightModelInfo,i as validateWebSceneError};