Jfoster126/v17customerfeedback (#36)

* Update documents with customer feedback

* Update document name

README.md

@@ -84,7 +84,7 @@ Released 06/30/2019 - (applies to [MeshPyramids](docs/1.7/store.cmn.md) profile)
 - Deprecated [SharedResource](docs/1.7/sharedResource.cmn.md) - sharedResource properties are readily available in the node index resource.
 - New [tooling to validate existing slpk](i3s_converter/i3s_converter_ReadMe.md) and convert Integrated Mesh or 3D Object scene layers to I3S 1.7.
 
-I3S specification version 1.7 is backwards compatible with I3S Version 1.6 and is currently supported by ArcGIS Pro 2.4 and ArcGIS Online.  More support of I3S 1.7 across the ArcGIS platform will role out in upcoming releases.
+I3S specification version 1.7 is backwards compatible with I3S Version 1.6 and is currently supported by ArcGIS Pro 2.4 and ArcGIS Online.  More support of I3S 1.7 across the ArcGIS platform will roll out in upcoming releases.
 
 ### Version 2.0
 

docs/1.6/lodSelection.cmn.md

@@ -11,7 +11,7 @@ These metrics are used by clients to determine the optimal resource access patte
 
 | Property | Type | Description |
 | --- | --- | --- |
-| **metricType** | string | <div>Possible values are:<ul><li>`maxScreenThreshold`: A per-node value for the maximum pixel size as measured in screen pixels. This value indicates the upper limit for the screen size of the diameter of the node's minimum bounding sphere (MBS). In other words, the content referenced by this node will qualify to be rendered only when the screen size is below the maximum screen threshold value. Used with the mesh pyramid profile.</li><li>`maxScreenThresholdSQ`: A per-node value for the maximum area of the projected bounding volume on screen in pixel squared. 3D Viewers may implement **look-angle dependent** node switching by comparing this metric with the area of the 2D outline of the oriented-bounding box (OBB) on screen. ( see [_"Fast Projected Area Computation for Three-Dimensional Bounding Boxes", Dieter Schmalstieg and Robert F. Tobler_](https://pdfs.semanticscholar.org/1f59/8266e387cf367702d16acf5a4e02cc72cb99.pdf) for an efficient algorithm). If a **look-angle independent** LOD switching is desired, viewers may use the area of minimum bounding-sphere (MBS) of the node if available or the MBS of the OBB otherwise. Note:  `maxScreenThresholdSQ` may be related to `maxScreenThreshold` as follow:  `maxScreenThresholdSQ = PI * 0.25 * maxScreenThreshold * maxScreenThreshold`</li><li>`screenSpaceRelative`: The scale of the node's minimum bounding volume. Used by the point profile.</li><li>`distanceRangeFromDefaultCamera`: Normalized distance of the node's minimum bounding volume from the camera. Used by the point profile.</li><li>`effectiveDensity`: Estimation of the point density covered by the node.  Used by the point cloud profile.</li></ul></div> |
+| **metricType** | string | <div>Possible values are:<ul><li>`maxScreenThreshold`: A per-node value for the maximum pixel size as measured in screen pixels. This value indicates the upper limit for the screen size of the diameter of the node's minimum bounding sphere (MBS). In other words, the content referenced by this node will qualify to be rendered only when the screen size is below the maximum screen threshold value. Used with the mesh pyramid profile.</li><li>`maxScreenThresholdSQ`: A per-node value for the maximum area of the projected bounding volume on screen in pixel squared. 3D Viewers may implement **look-angle dependent** node switching by comparing this metric with the area of the 2D outline of the oriented-bounding box (OBB) on screen. ( see [_"Fast Projected Area Computation for Three-Dimensional Bounding Boxes", Dieter Schmalstieg and Robert F. Tobler_](https://pdfs.semanticscholar.org/1f59/8266e387cf367702d16acf5a4e02cc72cb99.pdf) for an efficient algorithm). If a **look-angle independent** LOD switching is desired, viewers may use the area of minimum bounding-sphere (MBS) of the node if available or the MBS of the OBB otherwise. Note:  `maxScreenThresholdSQ` may be related to `maxScreenThreshold` as follow:  `maxScreenThresholdSQ = PI * 0.25 * maxScreenThreshold * maxScreenThreshold`</li><li>`screenSpaceRelative`: The scale of the node's minimum bounding volume. Used by the point profile.</li><li>`distanceRangeFromDefaultCamera`: The distance from the surface of the node's minimum bounding volume to the camera. Used by the point profile.</li><li>`effectiveDensity`: Estimation of the point density covered by the node.  Used by the point cloud profile.</li></ul></div> |
 | **maxError** | number | Maximum metric value, expressed in the CRS of the vertex coordinates or in reference to other constants such as screen size. |
 
 *Note: properties in **bold** are required*

docs/1.7/3Dobject_ReadMe.md

@@ -19,15 +19,16 @@ The 3D object scene layer is structured into a tree of multiple JSON files. A 3D
 - [Node Index Document](3DNodeIndexDocument.cmn.md)
 - [Statistics](statsInfo.cmn.md)
 - [Shared Resources](sharedResource.cmn.md)
-
 
 *Shared resources are deprecated as of version 1.7 and are only included for backwards compatibility.*
 
+3D object scene layer packages can optionally contain a [hash table](slpk_hashtable.cmn.md) for faster indexing. 
+
 *Example of 3DObject layer structure*
 
 ```
 .<host>/SceneServer/layers
-	+--0 // layer description
+	+--0 // scene layer document
 	+-- nodePages
 	|  +-- 0
 	|  +-- (...)
@@ -36,7 +37,6 @@ The 3D object scene layer is structured into a tree of multiple JSON files. A 3D
 	|  |  +-- attributes
 	|  |  |  +--f_2
 	|  |  |  +--f_4
-	|  |  |  +--f_8
 	|  |  |  +--(...)
 	|  |  +-- geometries
 	|  |  |  +-- 0
@@ -47,15 +47,10 @@ The 3D object scene layer is structured into a tree of multiple JSON files. A 3D
 	|  |  |  +-- 0_0_1
 	|  |  |  +--(...)
 	|  |  +-- shared 
-	|  +--1
-	|  |  (...) //same structure for all nodes
-	|  +--...
-	|  +-- 259
-	|  |  (...) //same structure for all nodes
+	|  |  (...) 
 	+--statistics
 	|  +-- f_2
 	|  +-- f_4
-	|  +-- f_8
 	|  +-- (...)
 ```
 # HTTP API Overview 1.7

docs/1.7/IntegratedMesh_ReadMe.md

@@ -16,6 +16,8 @@ The Integrated Mesh scene layer is structured into a tree of multiple JSON files
 
 *Shared resources and feature data are deprecated as of version 1.7 and are only included for backwards compatibility.*
 
+Integrated mesh scene layer packages can optionally contain a [hash table](slpk_hashtable.cmn.md) for faster indexing. 
+
 *Example of integrated mesh scene layer structure*
 
 ```

docs/1.7/lodSelection.cmn.md

@@ -11,7 +11,7 @@ These metrics are used by clients to determine the optimal resource access patte
 
 | Property | Type | Description |
 | --- | --- | --- |
-| **metricType** | string | <div>Possible values are:<ul><li>`maxScreenThreshold`: A per-node value for the maximum pixel size as measured in screen pixels. This value indicates the upper limit for the screen size of the diameter of the node's minimum bounding sphere (MBS). In other words, the content referenced by this node will qualify to be rendered only when the screen size is below the maximum screen threshold value. Used with the mesh pyramid profile.</li><li>`maxScreenThresholdSQ`: A per-node value for the maximum area of the projected bounding volume on screen in pixel squared. 3D Viewers may implement **look-angle dependent** node switching by comparing this metric with the area of the 2D outline of the oriented-bounding box (OBB) on screen. ( see [_"Fast Projected Area Computation for Three-Dimensional Bounding Boxes", Dieter Schmalstieg and Robert F. Tobler_](https://pdfs.semanticscholar.org/1f59/8266e387cf367702d16acf5a4e02cc72cb99.pdf) for an efficient algorithm). If a **look-angle independent** LOD switching is desired, viewers may use the area of minimum bounding-sphere (MBS) of the node if available or the MBS of the OBB otherwise. Note:  `maxScreenThresholdSQ` may be related to `maxScreenThreshold` as follow:  `maxScreenThresholdSQ = PI * 0.25 * maxScreenThreshold * maxScreenThreshold`</li><li>`screenSpaceRelative`: The scale of the node's minimum bounding volume. Used by the point profile.</li><li>`distanceRangeFromDefaultCamera`: Normalized distance of the node's minimum bounding volume from the camera. Used by the point profile.</li><li>`effectiveDensity`: Estimation of the point density covered by the node.  Used by the point cloud profile.</li></ul></div> |
+| **metricType** | string | <div>Possible values are:<ul><li>`maxScreenThreshold`: A per-node value for the maximum pixel size as measured in screen pixels. This value indicates the upper limit for the screen size of the diameter of the node's minimum bounding sphere (MBS). In other words, the content referenced by this node will qualify to be rendered only when the screen size is below the maximum screen threshold value. Used with the mesh pyramid profile.</li><li>`maxScreenThresholdSQ`: A per-node value for the maximum area of the projected bounding volume on screen in pixel squared. 3D Viewers may implement **look-angle dependent** node switching by comparing this metric with the area of the 2D outline of the oriented-bounding box (OBB) on screen. ( see [_"Fast Projected Area Computation for Three-Dimensional Bounding Boxes", Dieter Schmalstieg and Robert F. Tobler_](https://pdfs.semanticscholar.org/1f59/8266e387cf367702d16acf5a4e02cc72cb99.pdf) for an efficient algorithm). If a **look-angle independent** LOD switching is desired, viewers may use the area of minimum bounding-sphere (MBS) of the node if available or the MBS of the OBB otherwise. Note:  `maxScreenThresholdSQ` may be related to `maxScreenThreshold` as follow:  `maxScreenThresholdSQ = PI * 0.25 * maxScreenThreshold * maxScreenThreshold`</li><li>`screenSpaceRelative`: The scale of the node's minimum bounding volume. Used by the point profile.</li><li>`distanceRangeFromDefaultCamera`: The distance from the surface of the node's minimum bounding volume to the camera. Used by the point profile.</li><li>`effectiveDensity`: Estimation of the point density covered by the node.  Used by the point cloud profile.</li></ul></div> |
 | **maxError** | number | Maximum metric value, expressed in the CRS of the vertex coordinates or in reference to other constants such as screen size. |
 
 *Note: properties in **bold** are required*

docs/1.7/slpk_hashtable.cmn.md

@@ -0,0 +1,36 @@
+# SLPK Hash Table
+
+Scanning an SLPK (ZIP store) containing millions of documents is usually inefficient and slow.  A hash table file may be added to the SLPK to improve first load and file scanning performances.
+
+## To create SLPK hash table
+1. The offset of each file is known. For example, the byte offset from the beginning of the slpk file to the first byte of its ZIP local file header. See ZIP specification for reference.
+2. Convert all file paths to their canonical path. Canonical paths must:
+   - Be lower case
+   - Use a forward slash as the path separator `/`
+   - Not contain a heading forward slash
+   - Example: `/my/PATH.json` converts to `my/path.json`
+3. Compute the MD5 128 bit-hash for each canonical path to create an array of key-value pairs [MD5-digest ->Offset 64bit]. 
+
+4. Sort the key-value pairs by ascending keys using the following comparison based on little-endian architecture:
+```cpp
+	//for performance the following C++ comparator is used: (**little-endian**)
+	typedef std::array< unsigned char, 16 > md5_hash;
+	bool less_than( const md5_hash& hash_a, md5_hash& hash_b )
+	{
+	 const uint64* a = reinterpret_cast<const uint64*>(&hash_a[0]);	
+	 const uint64* b = reinterpret_cast<const uint64*>(&hash_b[0]);	
+	 return a[0] == b[0] ? a[1] < b[1] : a[0] < b[0];
+	}
+```
+5. Write this sorted array as the last file of the SLPK archive (last entry in the ZIP central directory). The file must be named  `@specialIndexFileHASH128@`. Each array element is 24-bytes long, which includes:
+   - 16 bytes for the MD5-digest and 8 bits for the offset
+   - Must be in little-endian order
+   - Must **not** contain padding
+   - Must  **not** contain a header
+## To read SLPK hash table
+1. Convert the input path to the canonical path and compute its MD5 hash (i.e. key).
+
+2. Search for key in the hash table. This can be easily implemented as a binary (i.e. dichotomic) search since the keys are sorted.
+
+3. Retrieve the file from the ZIP archive using the offset associated with key.
+

docs/2.0/pcsl_README.md → docs/2.0/pcsl_ReadMe.md

@@ -98,4 +98,4 @@ Example: http://my.server.com/PointCloudSceneLayer/SceneServer/layers/0/attribut
 - `layerID`: Integer. ID of the associated layer. Esri products expect this to be `0`.
 - `attributeID`: Integer.  ID of the specific attribute for the layer.
 
-Example: http://my.server.com/PointCloudSceneLayer/SceneServer/layers/0/statistics/64 
+Example: http://my.server.com/PointCloudSceneLayer/SceneServer/layers/0/statistics/64 

docs/2.0/slpk_hashtable.pcsl.md

@@ -0,0 +1,36 @@
+# SLPK Hash Table
+
+Scanning an SLPK (ZIP store) containing millions of documents is usually inefficient and slow.  A hash table file may be added to the SLPK to improve first load and file scanning performances.
+
+## To create SLPK hash table
+1. The offset of each file is known. For example, the byte offset from the beginning of the slpk file to the first byte of its ZIP local file header. See ZIP specification for reference.
+2. Convert all file paths to their canonical path. Canonical paths must:
+   - Be lower case
+   - Use a forward slash as the path separator `/`
+   - Not contain a heading forward slash
+   - Example: `/my/PATH.json` converts to `my/path.json`
+3. Compute the MD5 128 bit-hash for each canonical path to create an array of key-value pairs [MD5-digest ->Offset 64bit]. 
+
+4. Sort the key-value pairs by ascending keys using the following comparison based on little-endian architecture:
+```cpp
+	//for performance the following C++ comparator is used: (**little-endian**)
+	typedef std::array< unsigned char, 16 > md5_hash;
+	bool less_than( const md5_hash& hash_a, md5_hash& hash_b )
+	{
+	 const uint64* a = reinterpret_cast<const uint64*>(&hash_a[0]);	
+	 const uint64* b = reinterpret_cast<const uint64*>(&hash_b[0]);	
+	 return a[0] == b[0] ? a[1] < b[1] : a[0] < b[0];
+	}
+```
+5. Write this sorted array as the last file of the SLPK archive (last entry in the ZIP central directory). The file must be named  `@specialIndexFileHASH128@`. Each array element is 24-bytes long, which includes:
+   - 16 bytes for the MD5-digest and 8 bits for the offset
+   - Must be in little-endian order
+   - Must **not** contain padding
+   - Must  **not** contain a header
+## To read SLPK hash table
+1. Convert the input path to the canonical path and compute its MD5 hash (i.e. key).
+
+2. Search for key in the hash table. This can be easily implemented as a binary (i.e. dichotomic) search since the keys are sorted.
+
+3. Retrieve the file from the ZIP archive using the offset associated with key.
+