@dataforsyningen/saul 3.0.2 → 3.1.1

package/index.js

@@ -3,8 +3,9 @@
 export {
   image2world,
   world2image,
-  getZ,
-  iterate
+  getWorldXYZ,
+  getZ, // Deprecated. Use getElevation
+  iterate // Deprecated. Use getWorldXYZ
 } from './modules/saul-core.js'
 
 export {
@@ -19,3 +20,8 @@ export {
   epsg25832proj,
   createTranslator
 } from './modules/saul-projection.js'
+
+export {
+  getTerrainGeoTIFF,
+  getElevation
+} from './modules/saul-elevation.js'

package/modules/api.js

@@ -62,24 +62,31 @@ function getErrorMsg() {
   return error_msg
 }
 
-/** Returns JSON response data */
-function HttpResponseHandler(response) {
+/** Returns response data */
+function HttpResponseHandler(response, is_json) {
   if (!response.ok) {
     error_msg = response.status
     interruptLoading()
-    throw new Error(`HTTP error! Status: ${ response.status }`)
+    throw new Error(`HTTP error! ${ response.status }`)
   }
-  // We assume the returned data is JSON
-  return response.json()
+  if (is_json) {
+    // We assume the returned data is JSON
+    return response.json()
+  } else {
+    // Return whatever and let someone else worry about parsing it
+    return response
+  }
+  
 }
 
 /** 
  * GET HTTP responsee from API
  * @param {string} url - API service URL, including endpoint paths and query parameters.
  * @param {object} [config] - Custom request configs. See https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options
+ * @param {boolean} [is_json] - `true` if requested output is JSON
  * @returns {object} response object
  */
-function get(url, config = {}) {
+function get(url, config = {}, is_json = true) {
   if (!url) {
     console.error('Could not fetch data. Missing API URL')
   } else {
@@ -89,7 +96,7 @@ function get(url, config = {}) {
       method: 'GET'
     })
     .then((response) => {
-      return HttpResponseHandler(response)
+      return HttpResponseHandler(response, is_json)
     })
     .then((response) => {
       // Finally, return the parsed JSON response

package/modules/saul-core.js

@@ -3,6 +3,7 @@
  */
  
 import { getDHM } from './api.js'
+import { getElevation } from './saul-elevation.js'
 
 /** 
  * Converts x,y coordinates from an image to real world lat,lon coordinates
@@ -117,7 +118,7 @@ function radians(degrees) {
 }
 
 /** 
- * Fetches elevation based on X,Y coordinates using DHM/Koter endpoint
+ * (DEPRECATED - Use getElevation) Fetches elevation based on X,Y coordinates using DHM/Koter endpoint
  * @param {number} xcoor - EPSG:25832 X coordinate
  * @param {number} ycoor - EPSG:25832 Y coordinate
  * @param {{API_DHM_BASEURL: string, API_DHM_USERNAME: string, API_DHM_PASSWORD: string}} auth - API autentication data. See ../config.js.example for reference.
@@ -129,7 +130,7 @@ async function getZ(xcoor, ycoor, auth) {
   return z
 }
 
-/** Iterates guessing at a world coordinate using image coordinates and elevation info */
+/** (DEPRECATED - Use getWorldXYZ) Iterates guessing at a world coordinate using image coordinates and elevation info */
 function iterateRecursive(image_data, col, row, z, count, limit, auth, i) {
 
   // Get coordinates based on current z value
@@ -159,7 +160,7 @@ function iterateRecursive(image_data, col, row, z, count, limit, auth, i) {
 }
 
 /** 
- * Tries to guess world coordinate for a pixel position within an image using STAC API image data and requests to DHM elevation data.
+ * (DEPRECATED - Use getWorldXYZ) Tries to guess world coordinate for a pixel position within an image using STAC API image data and requests to DHM elevation data.
  * @param {object} image_data - image item data from STAC API
  * @param {number} col - image x coordinate (from left to right)
  * @param {number} row - image y coordinate (from top to bottom)
@@ -172,8 +173,25 @@ function iterate(image_data, col, row, auth, limit = 1) {
   return iterateRecursive(image_data, col, row, 0.5, 0, limit, auth, i)
 }
 
+/** Find world coordinate and elevation that correspond to image x,y. Uses image item information from STAC API and a GeoTIFF terrain model from Datafordeler.
+ * @param {object} options
+ * @param {array} options.xy - image coordinates
+ * @param {object} options.image - STAC API item
+ * @param {object} options.terrain - GeoTIFF object from getTerrainGeoTIFF() output
+ * @returns {array} Array with world coordinates (indexes 0 and 1) and elevation (index 2). Coordinates are EPSG:25832 format.
+ */
+async function getWorldXYZ(options) {
+
+  const world_xyz = image2world(options.image, options.xy[0], options.xy[1], 0)
+  world_xyz[2] = await getElevation(world_xyz[0], world_xyz[1], options.terrain)
+  const better_world_xyz = image2world(options.image, options.xy[0], options.xy[1], world_xyz[2])
+  
+  return better_world_xyz
+}
+
 export { 
   image2world,
+  getWorldXYZ,
   world2image,
   getZ,
   iterate

package/modules/saul-elevation.js

@@ -0,0 +1,86 @@
+import { fromArrayBuffer } from 'geotiff'
+import { get } from './api.js'
+
+/** Fetches a GeoTIFF with elevation data matching the bounding box of a STAC API item (image)
+ * @param {object} stac_item - STAC API item from a featureCollection request
+ * @param {{API_DHM_BASEURL: string, API_DHM_USERNAME: string, API_DHM_PASSWORD: string}} auth - API autentication data. See ../config.js.example for reference.
+ * @param {number} [fidelity] - Resolution fidelity. Higher number means more pixels and better precision. Between 1 and 0.01.
+ * @returns {object} GeoTiff data
+ */
+function getTerrainGeoTIFF(stac_item, auth, fidelity = 0.05) {
+  
+  const bbox = stac_item.bbox
+  const width = Math.round( stac_item.properties['proj:shape'][0] * fidelity )
+  const height = Math.round( stac_item.properties['proj:shape'][1] * fidelity )
+
+  // DHM data endpoint
+  let url = 'https://services.datafordeler.dk/DHMNedboer/dhm_wcs/1.0.0/WCS'
+  url += '?SERVICE=WCS&COVERAGE=dhm_terraen&RESPONSE_CRS=epsg:25832&CRS=epsg:25832&FORMAT=GTiff&REQUEST=GetCoverage&VERSION=1.0.0'
+  url += `&username=${ auth.API_DHM_USERNAME }&password=${ auth.API_DHM_PASSWORD }` // TODO: Should be auth stuff
+  url += `&height=${ height }`
+  url += `&width=${ width }`
+  url += `&bbox=${ bbox[0]},${ bbox[1]},${ bbox[2]},${ bbox[3]}`
+
+  return get(url, {}, false)
+  .then((response) => {
+    return response.arrayBuffer()
+  })
+  .then((arrayBuffer) => {
+    return consumeGeoTIFF(arrayBuffer)
+  })
+}
+
+async function consumeGeoTIFF(raw_data) {
+  const tiff = await fromArrayBuffer(raw_data)
+  const image = await tiff.getImage()
+  return image
+}
+
+function constrainToBbox(bbox, x, y) {
+  let new_x = x
+  let new_y = y
+  if (x < bbox[0]) {
+    new_x = bbox[0] + 1
+  } else if (bbox[2] < x) {
+    new_x = bbox[2] - 1
+  }
+  if (y < bbox[1]) {
+    new_y = bbox[1] + 1
+  } else if (bbox[3] < y) {
+    new_y = bbox[3] - 1
+  }
+  return [new_x, new_y]
+}
+
+/** Calculates nearest elevation for given coordinate using geoTIFF terrain data
+ * Heavily inspired by https://towardsdatascience.com/geotiff-coordinate-querying-with-javascript-5e6caaaf88cf
+ * @param {number} x - EPSG:25832 X coordinate
+ * @param {number} y - EPSG:25832 Y coordinate
+ * @param {object} geoTiff - GeoTiff data output from getTerrainGeoTIFF() method
+ * @returns {number} Elevation in meters 
+ */
+async function getElevation(x, y, geoTiff) {
+  
+  const bbox = geoTiff.getBoundingBox()
+  const height = geoTiff.getHeight()
+  const width = geoTiff.getWidth()
+  const bboxWidth = bbox[2] - bbox[0]
+  const bboxHeight = bbox[3] - bbox[1]
+
+  const xy = constrainToBbox(bbox, x, y)
+
+  const widthPct = ( xy[0] - bbox[0] ) / bboxWidth
+  const heightPct = ( xy[1] - bbox[1] ) / bboxHeight
+  const xPx = Math.floor( width * widthPct )
+  const yPx = Math.floor( height * ( 1 - heightPct ) )
+
+  const window = [ xPx, yPx, xPx + 1, yPx + 1 ]
+  const elevation_data = await geoTiff.readRasters( {window} )
+
+  return Math.round( elevation_data[0][0] * 10) / 10
+}
+
+export {
+  getTerrainGeoTIFF,
+  getElevation
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dataforsyningen/saul",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "description": "This is a collection of stand-alone methods for photogrammetry calculations and API interactions for 'Danske Skråfotos'.",
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "test": "echo 'TESTS WILL ONLY RUN UNDER NODE v18' && node ./test/saul-projection.test.js && node ./test/saul-core.test.js",
+    "test": "echo 'TESTS WILL ONLY RUN UNDER NODE v18' && node ./test/saul-projection.test.js && node ./test/saul-core.test.js && node ./test/saul-elevation.test.js",
     "docs": "jsdoc ./modules/*.js --destination docs"
   },
   "repository": {
@@ -27,6 +27,7 @@
     "jsdoc": "^3.6.10"
   },
   "dependencies": {
+    "geotiff": "^2.0.5",
     "proj4": "^2.8.0"
   }
 }

package/test/saul-elevation.test.js

@@ -0,0 +1,107 @@
+// You should add your own config.js with proper tokens, passwords, etc.
+// Check config.js.example for info on how to set it up
+import auth from '../config.js'
+
+import assert from 'assert'
+import { getTerrainGeoTIFF, getElevation } from '../modules/saul-elevation.js'
+import { get } from '../modules/api.js'
+import { getZ, getWorldXYZ, world2image } from '../modules/saul-core.js'
+
+// Vars
+const stac_item = '2021_83_29_2_0019_00003995'
+const fidelity = 0.05 // Higher number means more points and better precision
+const max_deviation = 0.5
+
+// STAC API endpoint
+let url_stac = 'https://api.dataforsyningen.dk/skraafotoapi_test/search?limit=1&crs=http://www.opengis.net/def/crs/EPSG/0/25832&token=9b554b6c854184c3b0f377ffc7481585'
+url_stac += `&ids=${ stac_item }`
+
+function is_equalIsh(num1, num2, deviation = max_deviation) {
+  if (Math.abs(num1 - num2) > deviation) {
+    return false
+  } else {
+    return true
+  }
+}
+
+function getRandomCoordinate(bbox) {
+  const x = bbox[0] + Math.random() * (bbox[2] - bbox[0])
+  const y = bbox[1] + Math.random() * (bbox[3] - bbox[1])
+  return [x,y]
+}
+
+function testGetElevationAnumberOfTimes(data, bbox, times) {
+  for (let i = 1; i <= times; i++) {
+    const world1 = getRandomCoordinate(bbox)
+    compareElevations(world1[0], world1[1], data)
+  }
+}
+
+function getRandomImageXY(image) {
+  const shapex = image.properties['proj:shape'][0]
+  const shapey = image.properties['proj:shape'][1]
+  const x = Math.floor(shapex - Math.random() * shapex)
+  const y = Math.floor(shapey - Math.random() * shapey)
+  return [x,y]
+}
+
+function testGetWorldXYZAnumberOfTimes(item, terrain, times) {
+  for (let i = 1; i <= times; i++) {
+    const xy = getRandomImageXY(item)
+    getWorldXYZ({
+      xy: xy,
+      image: item,
+      terrain: terrain
+    }).then(world_xy => {
+      compareElevations(world_xy[0], world_xy[1], terrain) // lower left corner of image
+      const image_coords = world2image(item, world_xy[0], world_xy[1], world_xy[2])
+      assert(is_equalIsh(image_coords[0], xy[0], 0.75), `Image x coordinates ${image_coords[0]} / ${xy[0]} do not match`)
+      assert(is_equalIsh(image_coords[1], xy[1], 0.75), `Image y coordinates ${image_coords[1]} / ${xy[1]} do not match`)
+      console.log('getWorldXYZ => world2image OK')
+    })
+  }
+}
+
+function compareElevations(x,y,geotiff) {
+  getElevation(x, y, geotiff)
+  .then(elevation => {
+    getZ(x, y, auth)
+    .then(getz_e => {
+      assert(is_equalIsh(getz_e, elevation), `Elevations ${elevation} / ${getz_e} at ${x} ${y} do not match`)
+      console.log(`Elevation at ${ x } ${ y } with delta ${Math.abs(elevation - getz_e).toFixed(2)} OK`)
+    })
+  })
+}
+
+// Test getTerrainGeoTIFF and getElevation with a STAC API item
+get(url_stac)
+.then((json) => {
+
+  const width = Math.round( json.features[0].properties['proj:shape'][0] * fidelity )
+  const height = Math.round( json.features[0].properties['proj:shape'][1] * fidelity )
+
+  console.info('fetching', width * height, 'data points as GeoTiff image')
+
+  getTerrainGeoTIFF(json.features[0], auth, fidelity)
+  .then(data => {
+
+    // Testing getElevation
+    try {
+      testGetElevationAnumberOfTimes(data, json.features[0].bbox, 5)
+    } catch(error) {
+      console.error(error)
+    }
+
+    // Testing getWorldXYZ
+    try {
+      testGetWorldXYZAnumberOfTimes(json.features[0], data, 10)
+    } catch(error) {
+      console.error(error)
+    }
+
+  })
+
+})
+.catch((err) => {
+  console.log('THE ERROR', err)
+})