feat: add device location height

.env.example

@@ -13,6 +13,11 @@ REFRESH_TOKEN_VALIDITY_MS=604800000 # 1 week
 
 NOMINATIM_SEARCH_API="https://nominatim.openstreetmap.org/search"
 
+OPENTOPO_DATA_API_URL="https://api.opentopodata.org/v1"
+# OpenTopoData returns the first non-null result from this ordered list.
+OPENTOPO_DATA_DATASET="eudem25m,mapzen"
+OPENTOPO_DATA_MIN_INTERVAL_MS="1100"
+
 OSEM_GITHUB_URL="https://github.com/openSenseMap/frontend"
 OSEM_API_URL="https://api.opensensemap.org/"
 DIRECTUS_URL="https://coelho.opensensemap.org"

README.md

@@ -6,7 +6,6 @@ running as a public beta at
 
 <img width="1510" height="858" alt="Screenshot OSeM" src="https://github.com/user-attachments/assets/70da4cff-1751-4a13-89e8-607a5198df37">
 
-
 ## Project setup
 
 If you do need to set the project up locally yourself, feel free to follow these
@@ -24,14 +23,19 @@ instructions:
 
 You can configure the API endpoint using the following environmental variables:
 
-| ENV          | Default value                                            |
-| ------------ | -------------------------------------------------------- |
-| OSEM_API_URL | https://api.testing.opensensemap.org                     |
-| DATABASE_URL | `postgresql://postgres:postgres@localhost:5432/postgres` |
+| ENV                           | Default value                                            |
+| ----------------------------- | -------------------------------------------------------- |
+| OSEM_API_URL                  | https://api.testing.opensensemap.org                     |
+| DATABASE_URL                  | `postgresql://postgres:postgres@localhost:5432/postgres` |
+| OPENTOPO_DATA_API_URL         | `https://api.opentopodata.org/v1`                        |
+| OPENTOPO_DATA_DATASET         | `eudem25m,mapzen`                                        |
+| OPENTOPO_DATA_MIN_INTERVAL_MS | `1100`                                                   |
 
 You can create a copy of `.env.example`, rename it to `.env` and set the values.
 To run a local development version, you only need to adjust the `OSEM_API_URL`
-to the one given above.
+to the one given above. Configure `OPENTOPO_DATA_API_URL` explicitly in
+production and point it to a self-hosted or managed instance; the default public
+instance is intended for development and evaluation.
 
 ### Setup Steps
 
@@ -163,11 +167,10 @@ flexibility to adjust the outputs to the needs of the respective use case.
 
 ##### Documenting an API Route
 
-API route documentation is generated from route-local `zod-openapi`
-definitions. Each API route can export an `openapi` object that describes the
-route's OpenAPI path item. Request bodies, response bodies, path parameters,
-query parameters, and headers should be described with Zod schemas wherever
-possible.
+API route documentation is generated from route-local `zod-openapi` definitions.
+Each API route can export an `openapi` object that describes the route's OpenAPI
+path item. Request bodies, response bodies, path parameters, query parameters,
+and headers should be described with Zod schemas wherever possible.
 
 The main benefit of this approach is that schemas can be shared between
 validation and documentation. This keeps the OpenAPI documentation closer to the

app/components/device/new/location-info.tsx

@@ -1,4 +1,4 @@
-import React, { useRef, useState, useEffect, useCallback } from 'react'
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useFormContext } from 'react-hook-form'
 import { useTranslation } from 'react-i18next'
 import {
@@ -11,6 +11,9 @@ import {
 import { Input } from '@/components/ui/input'
 import { Label } from '~/components/ui/label'
 import { BaseMap } from '~/components/base-map'
+import Spinner from '~/components/spinner'
+import { useTerrainElevation } from '~/hooks/use-terrain-elevation'
+import { calculateHeightAboveSeaLevel } from '~/lib/elevation'
 import { LOCATION_LIMITS, isValidLocation } from '~/lib/location'
 
 export function LocationStep() {
@@ -24,6 +27,7 @@ export function LocationStep() {
 	const { t } = useTranslation('newdevice')
 	const savedLatitude = watch('latitude')
 	const savedLongitude = watch('longitude')
+	const savedHeightAboveGround = watch('heightAboveGround')
 
 	const [marker, setMarker] = useState<{
 		latitude: number | string
@@ -35,108 +39,153 @@ export function LocationStep() {
 
 	useEffect(() => {
 		if (savedLatitude !== undefined && savedLongitude !== undefined) {
-			setMarker({
-				latitude: savedLatitude,
-				longitude: savedLongitude,
-			})
+			setMarker({ latitude: savedLatitude, longitude: savedLongitude })
 		}
 	}, [savedLatitude, savedLongitude])
 
-	const handleLatitudeChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-		const value = e.target.value.trim()
-		const parsedValue = parseFloat(value)
+	const markerLocation = useMemo(() => {
+		if (marker.latitude === '' || marker.longitude === '') return null
 
-		setMarker((prev) => ({
-			...prev,
-			latitude: value === '' || isNaN(parsedValue) ? '' : parsedValue,
-		}))
+		const candidate = {
+			latitude: Number(marker.latitude),
+			longitude: Number(marker.longitude),
+		}
 
-		setValue(
-			'latitude',
-			value === '' || isNaN(parsedValue) ? undefined : parsedValue,
-		)
+		return isValidLocation(candidate) ? candidate : null
+	}, [marker.latitude, marker.longitude])
+
+	const elevation = useTerrainElevation({
+		latitude: markerLocation?.latitude,
+		longitude: markerLocation?.longitude,
+	})
+
+	const finalHeight =
+		elevation.result === null
+			? null
+			: calculateHeightAboveSeaLevel(
+					elevation.result.elevation,
+					savedHeightAboveGround === '' ||
+						savedHeightAboveGround === undefined ||
+						savedHeightAboveGround === null
+						? undefined
+						: Number(savedHeightAboveGround),
+				)
+
+	const handleLatitudeChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+		const value = event.target.value.trim()
+		const parsedValue = Number(value)
+		const latitude =
+			value === '' || !Number.isFinite(parsedValue) ? '' : parsedValue
+
+		setMarker((current) => ({ ...current, latitude }))
+		setValue('latitude', latitude === '' ? undefined : latitude, {
+			shouldDirty: true,
+			shouldValidate: true,
+		})
 	}
 
-	const handleLongitudeChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-		const value = e.target.value.trim()
-		const parsedValue = parseFloat(value)
+	const handleLongitudeChange = (
+		event: React.ChangeEvent<HTMLInputElement>,
+	) => {
+		const value = event.target.value.trim()
+		const parsedValue = Number(value)
+		const longitude =
+			value === '' || !Number.isFinite(parsedValue) ? '' : parsedValue
 
-		setMarker((prev) => ({
-			...prev,
-			longitude: value === '' || isNaN(parsedValue) ? '' : parsedValue,
-		}))
+		setMarker((current) => ({ ...current, longitude }))
+		setValue('longitude', longitude === '' ? undefined : longitude, {
+			shouldDirty: true,
+			shouldValidate: true,
+		})
+	}
+
+	const handleHeightChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+		const value = event.target.value.trim()
+		const parsedValue = Number(value)
 
 		setValue(
-			'longitude',
-			value === '' || isNaN(parsedValue) ? undefined : parsedValue,
+			'heightAboveGround',
+			value === '' || !Number.isFinite(parsedValue) ? undefined : parsedValue,
+			{ shouldDirty: true, shouldValidate: true },
 		)
 	}
 
-	const onMarkerDrag = useCallback(
-		(event: MarkerDragEvent) => {
-			const { lng, lat } = event.lngLat
+	const updateMarker = useCallback(
+		(longitude: number, latitude: number) => {
+			const roundedLatitude = Math.round(latitude * 1_000_000) / 1_000_000
+			const roundedLongitude = Math.round(longitude * 1_000_000) / 1_000_000
+
 			setMarker({
-				latitude: Math.round(lat * 1000000) / 1000000,
-				longitude: Math.round(lng * 1000000) / 1000000,
+				latitude: roundedLatitude,
+				longitude: roundedLongitude,
+			})
+			setValue('latitude', roundedLatitude, {
+				shouldDirty: true,
+				shouldValidate: true,
+			})
+			setValue('longitude', roundedLongitude, {
+				shouldDirty: true,
+				shouldValidate: true,
 			})
-			setValue('latitude', lat)
-			setValue('longitude', lng)
 		},
 		[setValue],
 	)
 
+	const onMarkerDragEnd = useCallback(
+		(event: MarkerDragEvent) => {
+			updateMarker(event.lngLat.lng, event.lngLat.lat)
+		},
+		[updateMarker],
+	)
+
 	const onMapClick = useCallback(
-		(event: any) => {
-			const { lng, lat } = event.lngLat
-			setMarker({
-				latitude: Math.round(lat * 1000000) / 1000000,
-				longitude: Math.round(lng * 1000000) / 1000000,
-			})
-			setValue('latitude', lat)
-			setValue('longitude', lng)
+		(event: { lngLat: { lng: number; lat: number } }) => {
+			updateMarker(event.lngLat.lng, event.lngLat.lat)
 		},
-		[setValue],
+		[updateMarker],
 	)
 
+	const displayHeightValue =
+		savedHeightAboveGround !== undefined &&
+		savedHeightAboveGround !== null &&
+		savedHeightAboveGround !== ''
+			? String(savedHeightAboveGround)
+			: ''
+
 	return (
 		<div className="flex h-full w-full flex-col">
 			<div className="grow">
 				<BaseMap
 					ref={mapRef}
 					initialViewState={{
-						latitude: marker.latitude ? Number(marker.latitude) : 51,
-						longitude: marker.longitude ? Number(marker.longitude) : 7,
+						latitude: markerLocation?.latitude ?? 51,
+						longitude: markerLocation?.longitude ?? 7,
 						zoom: 3.5,
 					}}
 					onClick={onMapClick}
 				>
-					{isValidLocation({
-						latitude: Number(marker.latitude),
-						longitude: Number(marker.longitude),
-					}) && (
+					{markerLocation ? (
 						<Marker
-							latitude={Number(marker.latitude)}
-							longitude={Number(marker.longitude)}
+							latitude={markerLocation.latitude}
+							longitude={markerLocation.longitude}
 							anchor="center"
 							draggable
-							onDrag={onMarkerDrag}
+							onDragEnd={onMarkerDragEnd}
 						/>
-					)}
+					) : null}
 					<NavigationControl position="top-right" showCompass={false} />
 					<GeolocateControl
 						position="bottom-right"
 						positionOptions={{
 							enableHighAccuracy: true,
 							timeout: 10_000,
 						}}
-						fitBoundsOptions={{
-							maxZoom: 14,
-						}}
+						fitBoundsOptions={{ maxZoom: 14 }}
 					/>
 				</BaseMap>
 			</div>
 
-			<div className="bg-background flex w-full items-center justify-around p-4">
+			<div className="bg-background grid w-full gap-4 p-4 md:grid-cols-2 xl:grid-cols-3">
 				<div>
 					<Label htmlFor="latitude">{t('latitude')}</Label>
 					<Input
@@ -178,6 +227,75 @@ export function LocationStep() {
 						</p>
 					) : null}
 				</div>
+
+				<div>
+					<Label htmlFor="heightAboveGround">
+						{t('height_above_ground')} ({t('optional')})
+					</Label>
+					<Input
+						id="heightAboveGround"
+						type="number"
+						step="any"
+						{...register('heightAboveGround')}
+						value={displayHeightValue}
+						onChange={handleHeightChange}
+						placeholder={t('enter height above ground')}
+						aria-describedby="height-info height-error"
+						className="w-full rounded-md border p-2"
+					/>
+					<p id="height-info" className="text-muted-foreground mt-1 text-xs">
+						{t('height_info_text')}
+					</p>
+
+					{elevation.status === 'loading' ? (
+						<div className="mt-2 flex items-center gap-2">
+							<div className="h-4 w-4">
+								<Spinner />
+							</div>
+							<span className="text-muted-foreground text-sm">
+								{t('fetching_elevation')}
+							</span>
+						</div>
+					) : elevation.status === 'error' ? (
+						<div className="mt-2 text-sm text-amber-600">
+							<p>
+								{elevation.error === 'unavailable'
+									? t('elevation_unavailable')
+									: t('elevation_error')}
+							</p>
+							<button
+								type="button"
+								onClick={elevation.retry}
+								className="font-semibold underline"
+							>
+								{t('retry_elevation')}
+							</button>
+						</div>
+					) : elevation.result ? (
+						<div className="text-muted-foreground mt-2 text-sm">
+							<div>
+								{t('terrain_elevation')}:{' '}
+								{Math.round(elevation.result.elevation)} m
+							</div>
+							{finalHeight !== null ? (
+								<div>
+									{t('final_height')}: {Math.round(finalHeight)} m
+								</div>
+							) : null}
+							<div className="text-xs">
+								{t('elevation_source')}:{' '}
+								{elevation.result.attribution ?? elevation.result.dataset}
+								{elevation.result.datum ? ` (${elevation.result.datum})` : ''}
+							</div>
+						</div>
+					) : null}
+
+					{errors.heightAboveGround?.message ? (
+						<p id="height-error" className="mt-1 text-sm text-red-600">
+							{String(errors.heightAboveGround.message)}
+						</p>
+					) : null}
+				</div>
 			</div>
 		</div>
 	)