@dataforsyningen/saul 3.0.2 → 3.1.0

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,9 @@
  */
  
 import { getDHM } from './api.js'
+import { getElevation } from './saul-elevation.js'
+
+let iterations
 
 /** 
  * Converts x,y coordinates from an image to real world lat,lon coordinates
@@ -117,7 +120,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 +132,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 +162,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 +175,98 @@ 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) {
+
+  iterations = 1
+
+  const world_xyz = image2world(options.image, options.xy[0], options.xy[1], 0)
+  const better_world_xyz = await compareXYZ({
+    xy: options.xy,
+    image: options.image,
+    terrain: options.terrain,
+    world_xyz: Array.from(world_xyz),
+    limit: 0.5
+  })
+  return better_world_xyz
+}
+
+/**
+ * Adjusts elevation value if values are too far apart
+ * @param {number} z - elevation
+ * @param {number} delta_y - discrepancy value 
+ * @returns {number} Adjusted elevation number
+ */
+function adjustZ(z, delta_y) {
+  let new_z
+  if (delta_y < 0) {
+    new_z = z + 0.1
+  } else {
+    new_z = z - 0.1
+  }
+  console.log('z', new_z)
+  return new_z
+}
+
+/**
+ * Compares differences i x and y values
+ * @param {number} delta_x - x difference
+ * @param {number} delta_y - y difference
+ * @param {number} limit - difference may be within this limit
+ * @returns {boolean} Returns true if differences are within accepted limit
+ */
+function compareXY(delta_x, delta_y, limit) {
+  if (Math.abs(delta_x) > limit || Math.abs(delta_y) > limit) {
+    return false
+  } else {
+    return true
+  }
+}
+
+/** 
+ * Iterates world coordinate calculations in order to get a more precise result
+ * @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
+ * @param {array} options.world_xy - Array with (currently guessed) world coordinates (indexes 0 and 1) and elevation (index 2). Coordinates are EPSG:25832 format.
+ * @param {number} options.limit - Return when two guesses are within this limit
+ * @returns {array} Array with world coordinates (indexes 0 and 1) and elevation (index 2). Coordinates are EPSG:25832 format.
+ */
+async function compareXYZ(options) {
+
+  iterations++
+  if (iterations > 50) {
+    console.error('too many iterations')
+    return false
+  }
+
+  const z = await getElevation(options.xy[0], options.xy[1], options.terrain)
+  const world_xyz = image2world(options.image, options.xy[0], options.xy[1], z)
+  const delta_x = world_xyz[0] - options.world_xyz[0]
+  const delta_y = world_xyz[1] - options.world_xyz[1]
+  
+  if (!compareXY(delta_x, delta_y, options.limit)) {
+    
+    const new_options = Object.assign({},options)
+    new_options.world_xyz = Array.from(world_xyz)
+    new_options.world_xyz[2] = adjustZ(world_xyz[2], delta_x, delta_y)
+    return await compareXYZ(new_options)
+
+  } else {
+    return world_xyz
+  }
+}
+
 export { 
   image2world,
+  getWorldXYZ,
   world2image,
   getZ,
   iterate

package/modules/saul-elevation.js

@@ -0,0 +1,68 @@
+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
+}
+
+/** 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 widthPct = ( x - bbox[0] ) / bboxWidth
+  const heightPct = ( y - 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.0",
   "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,80 @@
+// 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 } 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) {
+  if (Math.abs(num1 - num2) > max_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 testDataAnumberOfTimes(data, bbox, times) {
+  for (let i = 1; i <= times; i++) {
+    const world1 = getRandomCoordinate(bbox)
+    compareElevations(world1[0], world1[1], data)
+  }
+}
+
+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) => {
+
+  console.log('Testing getTerrainGeoTIFF and getElevation')
+
+  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 => {
+
+    testDataAnumberOfTimes(data, json.features[0].bbox, 5)
+    
+    getWorldXYZ({
+      xy: [1,1],
+      image: json.features[0],
+      terrain: data
+    }).then(world_xy => {
+      compareElevations(world_xy[0], world_xy[1], data) // lower left corner of image
+    })
+
+  })
+
+})
+.catch((err) => {
+  console.log('THE ERROR', err)
+})