@dataforsyningen/saul 3.6.0 → 4.0.0

package/index.js

@@ -1,20 +1,9 @@
 // Import/export modules with their public methods
 
-export {
-  image2world,
-  world2image, // Deprecated. Use getImageXY
-  getWorldXYZ,
-  getImageXY,
-  getZ,
-  iterate // Deprecated. Use getWorldXYZ
-} from './modules/saul-core.js'
-
 export {
   postSTAC,
   getSTAC,
   getDHM,
-  getTerrainGeoTIFF,
-  getDenmarkGeoTiff,
   get,
   post
 } from './modules/api.js'
@@ -22,9 +11,22 @@ export {
 export {
   epsg25832proj,
   createTranslator
-} from './modules/saul-projection.js'
+} from './modules/projection.js'
 
 export {
   getElevation,
-  visualizeGeotiff
-} from './modules/saul-elevation.js'
+  visualizeGeotiff,
+  getZ,
+  getTerrainGeoTIFF,
+  getDenmarkGeoTiff,
+  getTerrainByBbox
+} from './modules/elevation.js'
+
+export {
+  getTotalBbox,
+  image2world,
+  world2image, // Deprecated. Use getImageXY
+  getWorldXYZ,
+  getImageXY,
+  iterate // Deprecated. Use getWorldXYZ
+} from './modules/image.js'

package/modules/api.js

@@ -2,8 +2,6 @@
  * SAUL API utilities
  */
 
-import { fromArrayBuffer } from 'geotiff'
-
 let error_msg
 let load_stack = []
 
@@ -194,77 +192,10 @@ function postSTAC(endpoint, data, auth) {
   .then((data) => data)
 }
 
-
-/** Converts raw GeoTIFF arrayBuffer to image */
-async function consumeGeoTIFF(raw_data) {
-  const tiff = await fromArrayBuffer(raw_data)
-  const image = await tiff.getImage()
-  return image
-}
-
-function calcSizeRatio(sizeX, bbox) {
-  const ratio = ( bbox[0] - bbox[2] ) / ( bbox[1] - bbox[3] )
-  return Math.round(sizeX * ratio)
-}
-
-
-/** 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_WCS_BASEURL: string, API_DHM_TOKENA: string, API_DHM_TOKENB: string}} auth - API autentication data. See ../config.js.example for reference.
- * @param {number} [resolution] - Resolution (1 - 0.01). Higher number means more pixels and better precision.
- * @returns {object} GeoTiff data
- */
-function getTerrainGeoTIFF(stac_item, auth, resolution = 0.05, sizeX = 300) {
-  
-  const bbox = stac_item.bbox
-  const sizeY = calcSizeRatio(sizeX, stac_item.bbox)
-  const width = stac_item.properties ? Math.round( stac_item.properties['proj:shape'][0] * resolution ) : sizeX
-  const height = stac_item.properties ? Math.round( stac_item.properties['proj:shape'][1] * resolution ) : sizeY
-
-  // GET request for DHM WCS data
-  let url = auth.API_DHM_WCS_BASEURL
-  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_TOKENA }&password=${ auth.API_DHM_TOKENB }`
-  url += `&height=${ height }`
-  url += `&width=${ width }`
-  url += `&bbox=${ bbox[0]},${ bbox[1]},${ bbox[2]},${ bbox[3]}`
-
-  return get(url, {cache: 'force-cache'}, false)
-  .then((response) => {
-    return response.arrayBuffer()
-  })
-  .then((arrayBuffer) => {
-    return consumeGeoTIFF(arrayBuffer)
-  })
-}
-
-/**
- * Fetches a geoTIFF with elevation data covering all of Denmark
- * @param {Object} options
- * @param {Object} options.src - URL to download a pre-generated GeoTiff.
- * @param {Object} options.auth - API autentication data. See ../config.js.example for reference.
- * @param {Number} options.size - Width of the geoTiff image to return
- * @returns GeoTIFF raster with elevation data
- */
-function getDenmarkGeoTiff(options) {
-  if (options.src) {
-    return fetch(options.src)
-    .then(response => response.arrayBuffer())
-    .then(arrayBuffer => consumeGeoTIFF(arrayBuffer))
-  } else {
-    const auth = options.auth
-    const size = options.size ? options.size : 1000
-    return getTerrainGeoTIFF({bbox: [430000,6040000,900000,6413000]}, auth, null, size)
-  }
-}
-
 export {
   get,
   post,
   getSTAC,
   postSTAC,
-  getDHM,
-  getTerrainGeoTIFF,
-  getDenmarkGeoTiff,
-  consumeGeoTIFF
+  getDHM
 }

package/modules/{saul-core.js → core.js}

@@ -2,7 +2,7 @@
  * SAUL photogrammetry utilities 
  */
  
-import { getDHM } from './api.js'
+
 import { getElevation } from './saul-elevation.js'
 
 /** 
@@ -136,19 +136,6 @@ function radians(degrees) {
   return degrees * (Math.PI / 180)
 }
 
-/** 
- * Fetches a single elevation value 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.
- * @returns {number} Elevation in meters 
- */
-async function getZ(xcoor, ycoor, auth) {
-  let zcoor_data = await getDHM(`?geop=POINT(${xcoor} ${ycoor})&elevationmodel=dtm`, auth)
-  let z = zcoor_data.HentKoterRespons.data[0].kote
-  return z
-}
-
 /** (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) {
 
@@ -239,7 +226,6 @@ export {
   world2image,
   getWorldXYZ,
   getImageXY,
-  getZ,
   iterate
 }
  

package/modules/elevation.js

@@ -0,0 +1,203 @@
+import { getDHM, get } from './api.js'
+import { fromArrayBuffer } from 'geotiff'
+
+/** Converts raw GeoTIFF arrayBuffer to image */
+async function consumeGeoTIFF(raw_data) {
+  const tiff = await fromArrayBuffer(raw_data)
+  const image = await tiff.getImage()
+  return image
+}
+
+function calcSizeRatio(sizeX, bbox) {
+  const ratio = ( bbox[0] - bbox[2] ) / ( bbox[1] - bbox[3] )
+  return Math.round(sizeX * ratio)
+}
+
+/** 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_WCS_BASEURL: string, API_DHM_TOKENA: string, API_DHM_TOKENB: string}} auth - API autentication data. See ../config.js.example for reference.
+ * @param {number} [resolution] - Resolution (1 - 0.01). Higher number means more pixels and better precision.
+ * @returns {object} GeoTiff data
+ */
+function getTerrainGeoTIFF(stac_item, auth, resolution = 0.05, sizeX = 300) {
+  
+  const bbox = stac_item.bbox
+  const width = stac_item.properties ? Math.round( stac_item.properties['proj:shape'][0] * resolution ) : sizeX
+
+  return getTerrainByBbox(bbox, auth, width)
+}
+
+/**
+ * Fetches a geoTIFF with elevation data covering all of Denmark
+ * @param {Object} options
+ * @param {Object} options.src - URL to download a pre-generated GeoTiff.
+ * @param {Object} options.auth - API autentication data. See ../config.js.example for reference.
+ * @param {Number} options.size - Width of the geoTiff image to return
+ * @returns GeoTIFF raster with elevation data
+ */
+function getDenmarkGeoTiff(options) {
+  if (options.src) {
+    return fetch(options.src)
+    .then(response => response.arrayBuffer())
+    .then(arrayBuffer => consumeGeoTIFF(arrayBuffer))
+  } else {
+    const auth = options.auth
+    const size = options.size ? options.size : 1000
+    return getTerrainByBbox([430000,6040000,900000,6413000], auth, size)
+  }
+}
+
+/**  
+ * Maps a coordinate from the one coordinate system to another based on GeoTiff image dimensions.
+ * @param {Array} coord - EPSG:25832 X,Y coordinate pair
+ * @param {Array} bbox - Bounding box within input coordinate systtem. Consists of 2 EPSG:25832 coordinate pairs. Example: [x1,y1,x2,y2]
+ * @param {Array} imageDimensions - Width and height of a GeoTiff image. This will set the bounding box of the output coordinate system. Note: This coordinate system will have 0,0 set in the top right position of the image.
+ */
+function convertCoordinate(coord, bbox1, imageDimensions) {
+  
+  // Extract the coordinates from the bounding boxes
+  const [x1_min, y1_min, x1_max, y1_max] = bbox1
+
+  // Extract the coordinate to convert
+  const [x1, y1] = coord
+
+  // Calculate the width and height of both bounding boxes
+  const width1 = x1_max - x1_min
+  const height1 = y1_max - y1_min
+  const width2 = imageDimensions[0]
+  const height2 = imageDimensions[1]
+
+  // Calculate the relative position in the first coordinate system
+  const x_relative = (x1 - x1_min) / width1
+  const y_relative = (y1 - y1_min) / height1
+
+  // Calculate the new position in the second coordinate system
+  const x2 = Math.abs(x_relative * width2)
+  const y2 = height2 - Math.abs(y_relative * height2)
+
+  return [x2, y2]
+}
+
+/** 
+ * Calculates nearest elevation for given coordinate using geoTIFF terrain data
+ * @param {number} x - EPSG:25832 X coordinate
+ * @param {number} y - EPSG:25832 Y coordinate
+ * @param {object} geoTiff - GeoTiff data output from getTerrainGeoTIFF() or getDenmarkGeoTiff() method
+ * @returns {number} Elevation in meters 
+ */
+async function getElevation(x, y, geoTiff) {
+
+  const bbox = geoTiff.getBoundingBox()
+  const height = geoTiff.getHeight()
+  const width = geoTiff.getWidth()
+
+  // Convert lat/lon to geotiff x/y
+  const [xPx, yPx] = convertCoordinate([x,y], bbox, [width, height])
+ 
+  // Fetch window of raster values around x/y
+  const window = [
+    Math.floor(xPx), 
+    Math.floor(yPx),
+    Math.ceil(xPx),
+    Math.ceil(yPx)
+  ]
+  
+  // Fetch elevation value from geoTiff rasters
+  const elevation_data = await geoTiff.readRasters({
+    window: window,
+    fillValue: 0
+  })
+  
+  return elevation_data[0][0]
+}
+
+/** Creates an ASCII visualization of a GeoTiff with terrain elevation data. Useful for display in a terminal.
+ * NOTE: You may want to use a downsmapled GeoTiff to fit within your terminal window. A GeoTiff pixel is represented by 3 characters each.
+ * @param {object} gTiff - GeoTiff output from getTerrainGeoTIFF() or getDenmarkGeoTiff() method
+ */
+async function visualizeGeotiff(gTiff) {
+  console.log('--- GTIFF visualization ---')
+  const float32Arr = await gTiff.readRasters()
+  const tiffWidth = gTiff.getWidth()
+  const rasters = float32Arr[0]
+  let lines = []
+  let line = ''
+  for (let i = 0; i < rasters.length; i++) {
+    if (i % tiffWidth === 0) {
+      lines.push(line)
+      line = ''
+    }
+    line += zeroPadNumber(rasters[i])
+  }
+  for (const l of lines) {
+    console.log(l)
+  }
+}
+
+/** Converts numbers to strings in a 3-letter format. Ex. `002`, `0-3` (for negative numbers), or `123` */
+function zeroPadNumber(input) {
+  if (input === 0) {
+      return "..."
+  } else if (input < 0) {
+      return `0${input.toFixed(0)}`
+  } else if (input < 10) {
+      return `00${Math.floor(input)}`
+  } else if (input < 100) {
+      return `0${Math.floor(input)}`
+  } else {
+      return `${Math.floor(input)}`
+  }
+}
+
+/** 
+ * Fetches a single elevation value 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.
+ * @returns {number} Elevation in meters 
+ */
+async function getZ(xcoor, ycoor, auth) {
+  let zcoor_data = await getDHM(`?geop=POINT(${xcoor} ${ycoor})&elevationmodel=dtm`, auth)
+  let z = zcoor_data.HentKoterRespons.data[0].kote
+  return z
+}
+
+/** Fetches a GeoTIFF with elevation data matching a bounding box of EPSG:25832 coordinates
+ * @param {Array} bbox - Bounding box array consisting of two sets of EPSG:25832 coordinates (ie. `[543049, 6153925, 544463, 6155221]`)
+ * @param {{API_DHM_WCS_BASEURL: string, API_DHM_TOKENA: string, API_DHM_TOKENB: string}} auth - API autentication data. See ../config.js.example for reference.
+ * @param {number} [sizeLimit] - Optional size limiter. Will request GeoTIFF with width that does not exceed this number. Default is 500
+ * @returns {object} GeoTiff data
+ */
+function getTerrainByBbox(bbox, auth, sizeLimit = 500) {
+
+  const width = sizeLimit
+  const height = Math.round(calcSizeRatio(sizeLimit, bbox))
+
+  // GET request for DHM WCS data
+  let url = auth.API_DHM_WCS_BASEURL
+  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_TOKENA }&password=${ auth.API_DHM_TOKENB }`
+  url += `&height=${ height }`
+  url += `&width=${ width }`
+  url += `&bbox=${ Math.round(bbox[0]) - 200 },${ Math.round(bbox[1]) - 200 },${ Math.round(bbox[2]) + 200},${ Math.round(bbox[3]) + 200}` // Add/subtract 200 meters to bbox to ensure coverage on the edges
+
+  return get(url, {cache: 'force-cache'}, false)
+  .then((response) => {
+    return response.arrayBuffer()
+  })
+  .then((arrayBuffer) => {
+    return consumeGeoTIFF(arrayBuffer)
+  })
+  .catch(error => {
+    return error
+  })
+}
+
+export {
+  getElevation,
+  visualizeGeotiff,
+  getZ,
+  getTerrainGeoTIFF,
+  getDenmarkGeoTiff,
+  getTerrainByBbox
+}

package/modules/image.js

@@ -0,0 +1,256 @@
+/**
+ * SAUL photogrammetry utilities 
+ */
+ 
+import { getElevation, getZ } from './elevation.js'
+
+/** 
+ * Converts x,y coordinates from an image to real world lat,lon coordinates
+ * @param {object} image_data - skraafoto-stac-api image data
+ * @param {number} col - Image x coordinate (from left to right). Should be a coordinate for the entire image, not just the part displayed in the viewport.
+ * @param {number} row - Image y coordinate (from top to bottom). Should be a coordinate for the entire image, not just the part displayed in the viewport.
+ * @param {number} [Z] - Elevation (geoide)
+ * @returns {array} [longitude, latitude, elevation] 
+ */
+function image2world(image_data, col, row, Z = 0) {
+
+  // constants pulled from image_data
+  const xx0  = image_data.properties['pers:interior_orientation'].principal_point_offset[0]
+  const yy0  = image_data.properties['pers:interior_orientation'].principal_point_offset[1]
+  const ci   = image_data.properties['pers:interior_orientation'].focal_length
+  const pix  = image_data.properties['pers:interior_orientation'].pixel_spacing[0]
+  const dimXi = image_data.properties['pers:interior_orientation'].sensor_array_dimensions[0]
+  const dimYi = image_data.properties['pers:interior_orientation'].sensor_array_dimensions[1]
+  const X0   = image_data.properties['pers:perspective_center'][0]
+  const Y0   = image_data.properties['pers:perspective_center'][1]
+  const Z0   = image_data.properties['pers:perspective_center'][2]
+  const Ome  = image_data.properties['pers:omega']
+  const Phi  = image_data.properties['pers:phi']
+  const Kap  = image_data.properties['pers:kappa']
+
+  // recalc values
+  var c = ci*(-1)
+  var dimX = dimXi*pix/2*(-1)
+  var dimY = dimYi*pix/2*(-1)
+  
+  // ... Do calculations ...
+  var o = radians(Ome)
+  var p = radians(Phi)
+  var k = radians(Kap)
+  var D11 =   Math.cos(p) * Math.cos(k)
+  var D12 = - Math.cos(p) * Math.sin(k)
+  var D13 =   Math.sin(p)
+  var D21 =   Math.cos(o) * Math.sin(k) + Math.sin(o) * Math.sin(p) * Math.cos(k)
+  var D22 =   Math.cos(o) * Math.cos(k) - Math.sin(o) * Math.sin(p) * Math.sin(k)
+  var D23 = - Math.sin(o) * Math.cos(p)
+  var D31 =   Math.sin(o) * Math.sin(k) - Math.cos(o) * Math.sin(p) * Math.cos(k)
+  var D32 =   Math.sin(o) * Math.cos(k) + Math.cos(o) * Math.sin(p) * Math.sin(k)
+  var D33 =   Math.cos(o) * Math.cos(p)
+
+  var x_dot = ((col*pix)-dimX*-1)-xx0
+  var y_dot = ((row*pix)-dimY*-1)-yy0
+
+  var kx = (D11*x_dot + D12*y_dot + D13*c)/(D31*x_dot + D32*y_dot + D33*c)
+  var ky = (D21*x_dot + D22*y_dot + D23*c)/(D31*x_dot + D32*y_dot + D33*c)
+
+  var X = (Z-Z0)*kx + X0
+  var Y = (Z-Z0)*ky + Y0
+
+  return[
+    Math.round(X * 100) / 100,
+    Math.round(Y * 100) / 100,
+    Z
+  ]
+}
+
+/** 
+ * Converts world lat,lon coordinates to x,y coordinates within a specific image
+ * @param {Object} image_data - skraafoto-stac-api image data
+ * @param {Number} Y - northing
+ * @param {Number} X - easting
+ * @param {Number} [Z] - elevation (geoide)
+ * @returns {array} [x,y] Column/row image coordinate 
+ */
+function getImageXY(image_data, X, Y, Z = 0) {
+
+  // constants pulled from image_data
+  const xx0  = image_data.properties['pers:interior_orientation'].principal_point_offset[0]
+  const yy0  = image_data.properties['pers:interior_orientation'].principal_point_offset[1]
+  const ci   = image_data.properties['pers:interior_orientation'].focal_length
+  const pix  = image_data.properties['pers:interior_orientation'].pixel_spacing[0]
+  const dimXi = image_data.properties['pers:interior_orientation'].sensor_array_dimensions[0]
+  const dimYi = image_data.properties['pers:interior_orientation'].sensor_array_dimensions[1]
+  const X0   = image_data.properties['pers:perspective_center'][0]
+  const Y0   = image_data.properties['pers:perspective_center'][1]
+  const Z0   = image_data.properties['pers:perspective_center'][2]
+  const Ome  = image_data.properties['pers:omega']
+  const Phi  = image_data.properties['pers:phi']
+  const Kap  = image_data.properties['pers:kappa']
+
+  // recalc values
+  var c = ci*(-1)
+  var dimX = dimXi*pix/2*(-1)
+  var dimY = dimYi*pix/2*(-1)
+  
+  // ... Do calculations ...
+  var o = radians(Ome)
+  var p = radians(Phi)
+  var k = radians(Kap)
+  var D11 =   Math.cos(p) * Math.cos(k)
+  var D12 = - Math.cos(p) * Math.sin(k)
+  var D13 =   Math.sin(p)
+  var D21 =   Math.cos(o) * Math.sin(k) + Math.sin(o) * Math.sin(p) * Math.cos(k)
+  var D22 =   Math.cos(o) * Math.cos(k) - Math.sin(o) * Math.sin(p) * Math.sin(k)
+  var D23 = - Math.sin(o) * Math.cos(p)
+  var D31 =   Math.sin(o) * Math.sin(k) - Math.cos(o) * Math.sin(p) * Math.cos(k)
+  var D32 =   Math.sin(o) * Math.cos(k) + Math.cos(o) * Math.sin(p) * Math.sin(k)
+  var D33 =   Math.cos(o) * Math.cos(p)
+
+  var x_dot = (-1)*c*((D11*(X-X0)+D21*(Y-Y0)+D31*(Z-Z0))/(D13*(X-X0)+D23*(Y-Y0)+D33*(Z-Z0)))
+  var y_dot = (-1)*c*((D12*(X-X0)+D22*(Y-Y0)+D32*(Z-Z0))/(D13*(X-X0)+D23*(Y-Y0)+D33*(Z-Z0)))
+
+  var col = ((x_dot-xx0)+(dimX))*(-1)/pix
+  var row = ((y_dot-yy0)+(dimY))*(-1)/pix
+
+  return [
+    Math.round(col),
+    Math.round(row)
+  ]
+}
+
+/** 
+ * (DEPRECATED - Use getImageXY) Converts lat,lon coordinates to x,y coordinates within a specific image
+ * @param {Object} image_data - skraafoto-stac-api image data
+ * @param {Number} Y - northing
+ * @param {Number} X - easting
+ * @param {Number} [Z] - elevation (geoide)
+ * @returns {array} [x,y] Column/row image coordinate 
+ */
+function world2image(image_data, X, Y, Z = 0) {
+  return getImageXY(image_data, X, Y, Z)
+}
+
+/** Converts degress to radians */
+function radians(degrees) {
+  return degrees * (Math.PI / 180)
+}
+
+/** (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
+  const worldcoor = image2world(image_data,col,row,z)
+
+  i--
+  if (i <= 0) {
+    // max iterations reached
+    return [worldcoor, 0, count]
+  }
+
+  // Get new z value from coordinates
+  return getZ(worldcoor[0],worldcoor[1], auth).then((new_z) => {
+    
+    // How big is the different between z and new z?
+    const delta = Math.abs(new_z - z)
+    
+    if (delta >= limit) {
+      // If the difference is too big, try building coordinates with the new z
+      count = count + 1
+      return iterateRecursive(image_data, col, row, new_z, count, limit, auth, i)
+    } else {
+      // If the difference is small, return coordinates
+      return [worldcoor, delta, count]
+    }
+  })
+}
+
+/** 
+ * (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)
+ * @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} [limit] - result may be inaccurate within this limit. Default is 1.
+ * @returns {array} [world coordindates (array), elevation discrepancy, calculation iterations]
+ */
+function iterate(image_data, col, row, auth, limit = 1) {
+  let i = 20 // Maximum number of iterations allowed
+  return iterateRecursive(image_data, col, row, 0.5, 0, limit, auth, i)
+}
+
+async function compareZ(options) {
+
+  // Get coordinates based on current z value
+  const world_xyz = image2world(options.image, options.xy[0], options.xy[1], options.z)
+  // Get new z value from coordinates
+  world_xyz[2] = await getElevation(world_xyz[0], world_xyz[1], options.terrain)
+  // How big is the different between z and new z?
+  const delta = Math.abs(world_xyz[2] - options.z)
+  
+  // Check delta vs. limit. If the difference is too big, try building coordinates with the new z
+  // Make sure the recursive loop ends after 20 iterations even if no precise z is found
+  if (options.iteration < 20 && delta > options.limit) {
+    options.iteration++
+    options.z = world_xyz[2]
+    return compareZ(options)
+  } else {
+    return world_xyz
+  }
+}
+
+/** 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
+ * @param {number} precision - Precision in meters for "good enough"
+ * @returns {array} Array with world coordinates (indexes 0 and 1) and elevation (index 2). Coordinates are EPSG:25832 format.
+ */
+async function getWorldXYZ(options, precision = 0.3) {
+  
+  const best_world_xyz = compareZ({
+    image: options.image,
+    terrain: options.terrain,
+    xy: options.xy,
+    z: 0,
+    limit: precision,
+    iteration: 1
+  })
+
+  return best_world_xyz
+}
+
+
+/** 
+ * Iterates over an array of STAC API image items 
+ * and returns a total bounding box for all the images
+ */
+function getTotalBbox(images) {
+  const initialBbox = images[0].features[0].bbox
+  
+  return images.reduce((bbox, image) => {
+    const imageBbox = image.features[0].bbox
+    if (imageBbox[0] < bbox[0]) {
+      bbox[0] = imageBbox[0]
+    }
+    if (imageBbox[1] < bbox[1]) {
+      bbox[1] = imageBbox[1]
+    }
+    if (imageBbox[2] > bbox[2]) {
+      bbox[2] = imageBbox[2]
+    }
+    if (imageBbox[3] > bbox[3]) {
+      bbox[3] = imageBbox[3]
+    }
+    return bbox
+  }, initialBbox)
+}
+
+export { 
+  image2world,
+  world2image,
+  getWorldXYZ,
+  getImageXY,
+  iterate,
+  getTotalBbox
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataforsyningen/saul",
-  "version": "3.6.0",
+  "version": "4.0.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",

package/test/saul-elevation.test.js

@@ -3,7 +3,7 @@
 import auth from '../config.js'
 
 import assert from 'assert'
-import { getElevation, get, getTerrainGeoTIFF, getZ, getWorldXYZ, world2image } from '../index.js'
+import { getElevation, get, getTerrainGeoTIFF, getZ, getWorldXYZ, world2image, getTerrainByBbox } from '../index.js'
 
 console.log('---------------')
 console.log('Elevation tests')
@@ -107,3 +107,12 @@ get(url_stac)
 .catch((err) => {
   console.log('THE ERROR', err)
 })
+
+// Testing getTerrainByBbox()
+try {
+  const gtiff = await getTerrainByBbox([542929.6729020511, 6153925.479277819, 544463.7189110086, 6155242.76541582], auth)
+  assert(gtiff.fileDirectory.ImageWidth === 500, 'GeoTIFF has weird dimensions')
+  console.log('Test getTerrainByBbox() => OK')
+} catch(error) {
+  console.error(error)
+}

package/example.html

@@ -1,58 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width">
-    <title>Saul modules example page</title>
-  </head>
-  <body>
-
-    <h1>Saul modules example</h1>
-
-    <p>Just opening this example.html file might not work becuase of CORS restrictions when trying to access STAC API.</p>
-    <p>You should run this HTML file from a simple server like Python's <code>http.server</code></p>
-
-    <h2>This is the result</h2>
-    <div id="result"></div>
-
-    <script type="module">
-
-      // You should add your own config.js with proper tokens, etc.
-      // Check config.js.example for info on how to set it up 
-      import auth from './config.js'
-      
-      import {image2world, world2image, getZ, iterate} from './modules/saul-core.js'
-      import {getSTAC} from './modules/api.js'
-
-      let xcoor = 579782.75
-      let ycoor = 6131096.03
-
-      const result_display_element = document.getElementById('result')
-      let apidata = await getSTAC('/collections/skraafotos2019/items/2019_83_37_2_0046_00001113', auth)
-
-      // Let's call an imported method
-      let zcoor = await getZ(xcoor, ycoor, auth)
-      
-      let image_coor = world2image(apidata, xcoor, ycoor, zcoor)
-      
-      let col = image_coor[0]
-      let row = image_coor[1]
-      
-      let world_coor = image2world(apidata, col, row, zcoor)
-      
-      col = 7375
-      row = 5382
-      let ite = await iterate(apidata, col, row, auth, 0.05)
-
-      // Write out result for the user to see
-      if (image_coor) {
-        result.innerText = xcoor + ' ' + ycoor + ' ' + zcoor + '\n' + image_coor[0] + '  ' + image_coor[1] + '\n' +ite
-      } else {
-        result.innerText = 'There was no result'
-      }
-      
-
-    </script>
-
-  </body>
-</html>

package/modules/saul-elevation.js

@@ -1,106 +0,0 @@
-/**  
- * Maps a coordinate from the one coordinate system to another based on GeoTiff image dimensions.
- * @param {Array} coord - EPSG:25832 X,Y coordinate pair
- * @param {Array} bbox - Bounding box within input coordinate systtem. Consists of 2 EPSG:25832 coordinate pairs. Example: [x1,y1,x2,y2]
- * @param {Array} imageDimensions - Width and height of a GeoTiff image. This will set the bounding box of the output coordinate system. Note: This coordinate system will have 0,0 set in the top right position of the image.
- */
-function convertCoordinate(coord, bbox1, imageDimensions) {
-  
-  // Extract the coordinates from the bounding boxes
-  const [x1_min, y1_min, x1_max, y1_max] = bbox1
-
-  // Extract the coordinate to convert
-  const [x1, y1] = coord
-
-  // Calculate the width and height of both bounding boxes
-  const width1 = x1_max - x1_min
-  const height1 = y1_max - y1_min
-  const width2 = imageDimensions[0]
-  const height2 = imageDimensions[1]
-
-  // Calculate the relative position in the first coordinate system
-  const x_relative = (x1 - x1_min) / width1
-  const y_relative = (y1 - y1_min) / height1
-
-  // Calculate the new position in the second coordinate system
-  const x2 = Math.abs(x_relative * width2)
-  const y2 = height2 - Math.abs(y_relative * height2)
-
-  return [x2, y2]
-}
-
-/** 
- * Calculates nearest elevation for given coordinate using geoTIFF terrain data
- * @param {number} x - EPSG:25832 X coordinate
- * @param {number} y - EPSG:25832 Y coordinate
- * @param {object} geoTiff - GeoTiff data output from getTerrainGeoTIFF() or getDenmarkGeoTiff() method
- * @returns {number} Elevation in meters 
- */
-async function getElevation(x, y, geoTiff) {
-
-  const bbox = geoTiff.getBoundingBox()
-  const height = geoTiff.getHeight()
-  const width = geoTiff.getWidth()
-
-  // Convert lat/lon to geotiff x/y
-  const [xPx, yPx] = convertCoordinate([x,y], bbox, [width, height])
- 
-  // Fetch window of raster values around x/y
-  const window = [
-    Math.floor(xPx), 
-    Math.floor(yPx),
-    Math.ceil(xPx),
-    Math.ceil(yPx)
-  ]
-  
-  // Fetch elevation value from geoTiff rasters
-  const elevation_data = await geoTiff.readRasters({
-    window: window,
-    fillValue: 0
-  })
-  
-  return elevation_data[0][0]
-}
-
-/** Creates an ASCII visualization of a GeoTiff with terrain elevation data. Useful for display in a terminal.
- * NOTE: You may want to use a downsmapled GeoTiff to fit within your terminal window. A GeoTiff pixel is represented by 3 characters each.
- * @param {object} gTiff - GeoTiff output from getTerrainGeoTIFF() or getDenmarkGeoTiff() method
- */
-async function visualizeGeotiff(gTiff) {
-  console.log('--- GTIFF visualization ---')
-  const float32Arr = await gTiff.readRasters()
-  const tiffWidth = gTiff.getWidth()
-  const rasters = float32Arr[0]
-  let lines = []
-  let line = ''
-  for (let i = 0; i < rasters.length; i++) {
-    if (i % tiffWidth === 0) {
-      lines.push(line)
-      line = ''
-    }
-    line += zeroPadNumber(rasters[i])
-  }
-  for (const l of lines) {
-    console.log(l)
-  }
-}
-
-/** Converts numbers to strings in a 3-letter format. Ex. `002`, `0-3` (for negative numbers), or `123` */
-function zeroPadNumber(input) {
-  if (input === 0) {
-      return "..."
-  } else if (input < 0) {
-      return `0${input.toFixed(0)}`
-  } else if (input < 10) {
-      return `00${Math.floor(input)}`
-  } else if (input < 100) {
-      return `0${Math.floor(input)}`
-  } else {
-      return `${Math.floor(input)}`
-  }
-}
-
-export {
-  getElevation,
-  visualizeGeotiff
-}