Unit conversion

A .well file always stores canonical SI units: meters, millimeters, m³/h, kW, m³ (Units). People read and type inches, feet, gallons and horsepower. @welldot/core provides the conversions so that every program converts the same way: to SI when writing, from SI when displaying.

import { inchesToMm, metersToFeet, slotNumberToMm } from '@welldot/core';

inchesToMm(10); // 254, for a 10 in borehole
slotNumberToMm(20); // 0.508, a slot-20 screen
metersToFeet(60); // 196.85…

Results are not rounded; format them for display (for example with formatNumber from @welldot/utils).

The helpers

Every function has a page in the API reference.

Converting by a user's preference

For flow, power and volume there are paired helpers that take the display unit as an argument. They fit a settings screen where the user picks units once:

import {
  flowFromCanonical,
  flowToCanonical,
  type FlowUnits,
} from '@welldot/core';

const unit: FlowUnits = 'L/s'; // 'm3/h' | 'L/s' | 'gpm'

flowFromCanonical(36, unit); // 10, to show a stored 36 m³/h
flowToCanonical(10, 'gpm'); // 2.27…, to store a typed 10 gpm

powerFromCanonical / powerToCanonical take 'kW' | 'cv' | 'hp', and volumeFromCanonical / volumeToCanonical take 'm3' | 'L' | 'ft3' | 'gal' (US gallon). The Units type groups the preferences (length, diameter, flow, power, volume) and is what @welldot/render accepts.

Diameters and slots: the traps

• Nominal sizes are not diameters. inchesToMm(6) is 152.4 mm, but 6 in steel pipe has an outer diameter of 168.3 mm, and the file stores the real outer diameter (as-built convention). Use the conversion for boreholes and true measurements; map trade sizes to real diameters in your input form.
• Slot numbers are thousandths of an inch: slotNumberToMm(20) is 0.508 mm (screen slot).

Coordinates

import { decimalDegreesToDms, dmsToDecimalDegrees } from '@welldot/core';

decimalDegreesToDms(-1.4558, 'lat');
// { degrees: 1, minutes: 27, seconds: 20.88, direction: 'S' }

dmsToDecimalDegrees({
  degrees: 1,
  minutes: 27,
  seconds: 20.88,
  direction: 'S',
});
// -1.4558

Projected coordinates (UTM) are out of scope: convert them with a projection library such as proj4 before writing location (CRS scope).

Laboratory reports

Lab reports use many unit spellings. These helpers map them onto the file's conventions (water quality units):

import {
  concentrationToCanonical,
  expandedToStandardUncertainty,
  normalizeColorUnit,
  turbidityCodeForUnit,
} from '@welldot/core';

concentrationToCanonical(50, 'ug/L'); // 0.05 mg/L
turbidityCodeForUnit('NTU'); // 'turbidity_ntu', the parameter code to use
normalizeColorUnit('mg Pt-Co/L'); // 'uH'
expandedToStandardUncertainty(0.04); // 0.02, U / k with k = 2, for value_precision

The last one implements the spec's rule that value_precision is one standard deviation, not the expanded uncertainty (precision).