Mapping toolbox
The TheTechIdea.OilGas.Mapping package. Settings: toolboxes.mapping in the environment.
Contour maps and 3D views of well data - gridding, contouring, maps from tops, thickness and net pay, and a 3D scene - on the same environment (units, theme, locale, labels) and drawing layer as every other view. This page grows with the toolbox; what is built so far is described below.
Gridding
Gridding.Run(points, method, spec) turns scattered points (ScatterPoint: easting, northing in metres, value) into a regular grid (Grid; a node with no value is
blank). Without a GridSpec it covers the data's extent plus mapping.extentMargin (10 % each side) with mapping.gridCellSize cells - unset, the longer side is
divided into mapping.defaultCellCount (100) cells; mapping.maxGridNodes (25 million) refuses a grid too fine to hold.
Inverse-distance weighting (InverseDistance; Shepard 1968) is a weighted mean of the data, weight 1 / d^p (mapping.idwPower, 2 as Shepard chose;
mapping.idwNeighbours, none = every point). It is exact at the data and never goes beyond their range - and flat at every datum, so it cannot make a ridge or a
trough that no well found.
Minimum curvature (MinimumCurvature; Briggs 1974) is the smoothest surface through the data, the solution of the biharmonic equation. It is solved here as the
biharmonic (thin-plate) spline, directly (Sandwell 1987), not by relaxing a grid: it is exact at the data and exact for a plane, does not depend on the grid, and is the
same every time. Its cost grows with the cube of the number of points, so mapping.maxSplinePoints (2000) refuses more (use inverse-distance weighting or fewer
points). The price of smoothness (Smith and Wessel 1990): between the data the surface can swing beyond their range. The result says so, in its notes and its QC.
Ordinary kriging (OrdinaryKriging; Matheron 1963) is the best linear unbiased estimate from a model of how values correlate with distance - a variogram - and the only method here
that also says how uncertain each node is: result.StandardDeviation is a second grid, the standard deviation of the error, zero at a datum and growing away from the data until, beyond the variogram's range,
no datum says anything and it stops growing (it is a surface like any other: contour it, map it, or mapping.maxKrigingStdDev leaves blank every node more uncertain than that). The variogram is
mapping.variogramModel (spherical, exponential or gaussian, all with a practical range, so that the sill is reached or 95 % of it reached at the range) with a nugget, a sill and a range. Give them with
mapping.variogramSill and mapping.variogramRange (and mapping.variogramNugget, 0 when omitted) - or give none and the model is fitted to the data: Matheron's estimator in mapping.variogramLags (15) lags up to half the largest
separation, fitted by weighted least squares with Cressie's (1985) weights, which favour the short lags that matter most. For a given range the nugget and sill are a linear problem and only the range is searched, so there is no optimiser
to get stuck, and exact semivariances return exactly the model that made them. Each node is kriged from its mapping.krigingNeighbours (24) nearest points (none: all). result.Variogram and the notes say which variogram was used and
whether it was given or fitted. A fit refuses data with no spatial correlation at the spacing they were sampled - a pure nugget - rather than invent a range; give a variogram yourself, or use inverse-distance weighting. Kriging
assumes the values vary around a constant mean (a stationary field): a strong regional trend, such as a dome, makes the fitted sill and range large, and it can go slightly beyond the data between them, as minimum curvature can - but, on the same wells, far less
(the notes say so). It is exact at the data. The Gaussian model needs a nugget: without one the kriging system is nearly singular.
Lengths in the settings (gridCellSize, coincidentTolerance, maxExtrapolationDistance, variogramRange, wellPathStep) are read in their unit - metres, feet, kilometres, miles, yards, inches, millimetres, centimetres, and any
length the environment adds under units.definitions. A unit that is not a length there is an error that names the setting, where once it was ignored: a mask given in a unit the catalogue did not know masked nothing, without a word.
QC (result.Qc) is what a geologist checks first: the surface minus the datum at every point (zero where the method honours the data), whether the surface goes
beyond the data's range, and the distance from every node to the nearest datum - how far each part of the map is from any evidence. mapping.maxExtrapolationDistance
(none by default) leaves nodes farther than that blank; without it every node beyond the data is a guess, and the QC says how far. Points closer than mapping.coincidentTolerance (1 mm) to one
another are averaged into one (and the notes say so); three points on a line cannot define a surface and are refused.
What it cannot do. Faults: gridding smooths across them, so a machine-gridded map is a starting surface with QC, not an interpretation. No tension splines. Kriging is ordinary and isotropic: no trend (universal kriging), no co-kriging, and the same range in every direction.
Grid.Minus(other) subtracts two grids of one geometry - the thickness between two surfaces.
Coordinate systems
A map needs positions in metres; wells are recorded as latitude and longitude, or in the grid of their country. A coordinate system here is a definition held in the environment - a method, an ellipsoid or datum, and the parameters - not something the program knows by heart, so any country's system can be added without a release.
{ "toolboxes": { "mapping": {
"coordinateSystems": { "EPSG:28992": { "method": "obliqueStereographic", "datum": "Amersfoort",
"latitudeOfOrigin": 52.1561605555556, "longitudeOfOrigin": 5.38763888888889, "scaleFactor": 0.9999079, "falseEasting": 155000, "falseNorthing": 463000 } },
"datums": { "Amersfoort": { "ellipsoid": "Bessel 1841", "toWgs84": { "tx": 565.4171, "ty": 50.3319, "tz": 465.5524, "rx": -0.398957, "ry": 0.343988, "rz": -1.8774, "scale": 4.0725 } } } } } }
Methods: transverseMercator (UTM, Gauss-Krueger and the national grids built on them - 189 of the 191 systems the country presets cite), lambertConformalConic (one or two standard parallels), obliqueStereographic,
albersEqualArea, mercator, polarStereographic, lambertAzimuthalEqualArea, cassiniSoldner, hotineObliqueMercatorA, hotineObliqueMercatorB, krovak, lambertConformalConicBelgium, pseudoMercator, equidistantCylindrical, lambertCylindricalEqualArea, equalEarth, colombiaUrban, americanPolyconic, krovakModified and geographic (longitude, latitude). Transverse Mercator uses the Krueger series to sixth order (Karney 2011); the others follow EPSG guidance
note 7-2 and Snyder's Map Projections - A Working Manual (USGS PP 1395). Angles are in degrees; false easting and northing are in the system's linear unit (linearUnitMetres: 1 for metres, 0.3048006096012192 for US survey feet).
| Method | How a definition says which variant | EPSG methods |
|---|---|---|
albersEqualArea |
standardParallel1 and standardParallel2 (one parallel only is allowed), latitudeOfOrigin and longitudeOfOrigin of the false origin |
9822 |
mercator |
variant A: scaleFactor at the equator (the origin is on the equator); variant B: standardParallel1, the parallel of true scale. Undefined at the poles, and refused there |
9804, 9805 |
polarStereographic |
variant A: latitudeOfOrigin 90 or -90 and scaleFactor; variant B: standardParallel1, the latitude of true scale (its sign picks the pole). The south pole is the north pole mirrored |
9810, 9829 |
cassiniSoldner |
latitudeOfOrigin and longitudeOfOrigin, no scale factor. The series of the guidance note, whose inverse is refined until it inverts the forward exactly; exact formulas on a sphere. Accurate within a few degrees of the central meridian |
9806 |
hotineObliqueMercatorA, hotineObliqueMercatorB |
latitudeOfOrigin and longitudeOfOrigin of the projection centre, azimuth of the initial line, rectifiedGridAngle (none: the azimuth), scaleFactor on the initial line. Variant B puts the false coordinates at the projection centre, variant A at the vertex of the initial line, which can be thousands of kilometres away |
9812, 9815 |
krovak |
latitudeOfOrigin and longitudeOfOrigin of the centre, scaleFactor on the pseudo standard parallel, pseudoStandardParallel and coneAxisColatitude - parameters of the definition, as in the dataset, not constants of the program. The dataset's Krovak has southing then westing axes: "axes": "sw" |
9819, 1041 |
lambertConformalConic |
one or two standard parallels. One: latitudeOfOrigin is the natural origin where scaleFactor applies, and falseOriginLatitude (variant B) is where the false coordinates are, when it is another latitude. ellipsoidScalingFactor multiplies every length (the Michigan conic: 1.0000382) |
9801, 9802, 1102, 1051 |
lambertConformalConicBelgium |
as the two-parallel Lambert, with the method's own rotation of 29.2985 arc-seconds: the dataset's longitude of false origin (4 21 24.983) is moved east by that over the cone constant, to the 4 22 02.952 of the plain system EPSG:31370 | 9803 |
pseudoMercator |
no parameters but the origin: the Mercator of a sphere with the ellipsoid's semi-major axis, the latitude taken as geodetic (web maps, EPSG:3857). Refused at the poles | 1024 |
equidistantCylindrical |
standardParallel1 (the equator when none), latitudeOfOrigin for the false northing |
1028, 1029 |
lambertCylindricalEqualArea |
standardParallel1; for the spherical form give an ellipsoid with inverseFlattening 0 (the generator uses the authalic sphere) |
9835, 9834 |
colombiaUrban |
latitudeOfOrigin, longitudeOfOrigin, projectionPlaneHeight (metres): a transverse projection whose lengths are carried up to a plane at that height above the ellipsoid, so that a city grid measures ground distance. The guidance note's closed-form inverse is approximate; the engine refines it so that the inverse is exact |
1052 |
americanPolyconic |
the origin only: each parallel is an arc of its own cone, true to length; the central meridian and the equator are straight. The inverse is by iteration | 9818 |
krovakModified |
as krovak, with the Czech Land Survey Office's polynomial correction of the southing and westing (method constants - an evaluation point and ten coefficients - not parameters of a system). For the north-orientated systems the dataset's false origin is added to the westing and southing, which are then negated, so as an east-north system it is the negative of the dataset's: the generator writes it so |
1042, 1043 |
azimuthalEquidistant |
the centre, latitudeOfOrigin and longitudeOfOrigin: lengths from the centre are true in every direction. On an ellipsoid that is a geodesic (see Geodesics below), so it is exact however far from the centre - the Equi7 continental grids reach 10 000 km; with the centre at a pole it is the meridian distance; on a sphere the great circle, and the point opposite the centre is refused |
1125 |
modifiedAzimuthalEquidistant |
the centre only: EPSG's series for the Yap Islands, an approximation of the exact form for an area of a few hundred kilometres. Against the exact geodesic its error is 0.08 mm at 800 km and 9 mm at 1 600 km, falling as the seventh power of the distance; beyond 3 200 km it is refused, naming azimuthalEquidistant |
9832 |
guam |
the centre only: the Clarke series for Guam, a closed form with an iterative inverse (taken to convergence; PROJ stops after three iterations) | 9831 |
equalEarth |
longitudeOfOrigin only: the authalic latitude and radius of the ellipsoid, with the published polynomial |
1078 |
lambertAzimuthalEqualArea |
latitudeOfOrigin' andlongitudeOfOrigin: oblique, equatorial (0) or polar (90, -90) as the latitude says. Refused at the point opposite the centre. The spherical form (EPSG 1027) is the same on a sphere: give an ellipsoid withinverseFlattening` 0 - on an ellipsoidal datum EPSG says to use the authalic sphere, radius a sqrt(qP / 2), which the generator does |
9820, 1027 |
Geodesics. Geodesic (equatorial radius and flattening) solves the two classical problems on an ellipsoid of revolution: Inverse - the shortest path between two points, its length in metres and its azimuth at each end - and Direct - the point reached from
another by a distance along an azimuth. It is Karney's algorithm (Algorithms for geodesics, J. Geodesy 87, 2013, with the series to order 6), written from the published algorithm and checked against its reference implementation, GeographicLib (MIT licence; see THIRD-PARTY-NOTICES.md);
tools/crs/geodesic_tables.py reads the coefficient tables from that source, so they are not typed. It is accurate to nanometres for any two points, nearly antipodal ones included, where Vincenty's iteration fails. Against PROJ's geodesic functions on seven ellipsoids - WGS 84, Clarke 1866, International 1924, Bessel, a sphere, a prolate spheroid
and a strongly flattened one, to exercise every branch - 1 526 inverse, 1 113 direct and 427 antipodal cases agree to 3.7 nanometres in length and 2.4e-10 degrees in azimuth (lines over a kilometre; a shorter line's azimuth is limited by the resolution of its coordinates, about 1.8e-7 / length-in-metres degrees, and the test uses that bound).
Independently of any geodesic code the tests check meridian lengths against a numerical integral of the meridional radius of curvature, the equator against a times the longitude, a sphere against the haversine and bearing formulas, and the round trip of the two problems.
Prime meridians. Some national systems count their longitudes from a meridian other than Greenwich - Ferro (the Austrian and Czech systems of the Habsburg survey), Paris, Oslo, Lisbon, Madrid, Brussels, Bern, Jakarta - and give their
longitudeOfOrigin from it too. primeMeridian is that meridian in degrees east of Greenwich (-17.66667 for Ferro, 2.33722917 for Paris, 10.72291667 for Oslo, 106.80771944 for Jakarta): the system subtracts it from a longitude before projecting and adds it back
after, so the program's own longitudes are always from Greenwich, and a system with meridian P and origin L is exactly a Greenwich system with origin L + P (the tests check this for five methods and six meridians, across the antimeridian). The dataset gives a meridian in
its own unit - Paris in grads, 2.5969213 grads being 2.33722917 degrees - and so counts the angles of such a system; the generator converts both. All 39 current EPSG systems on these meridians match PROJ to the millimetre.
Axes. axes says which way x and y increase, as two letters, the first for x: en (east, north - the usual and the default), wn, ws, es - or, when a system lists the north-south coordinate first, ne, nw, sw, se. The false easting always goes with the east-west coordinate, whichever comes first (Krovak adds it to the westing). A "south orientated" or "west orientated" system is the same projection with its axes turned, so it
is written as that projection plus axes: South Africa's and Namibia's Lo systems are transverseMercator with "axes": "ws" (westing, southing: Westing = FE - E, Southing = FN - N, EPSG guidance note 7-2), Greenland's
are lambertConformalConic with "axes": "wn", and the Czech and Slovak Krovak is krovak with "axes": "sw" (southing, westing; PROJ lists it in that order). Eight south-orientated systems (Hartebeesthoek94, Cape, Schwarzeck) match PROJ to the millimetre both ways. PROJ cannot express the west-orientated Lambert systems at all, so there
is no independent oracle for them: they are checked by the property that defines them (the Lambert already checked against PROJ, with x turned about the false origin). CoordinateSystem.KnownMethods lists the methods the engine has.
UTM needs no definition: utm:38N, utm:12S (and utm:32N:ED50 on another datum) are generated from the zone; geographic and geographic:<datum> are generated too.
Ellipsoids (mapping.ellipsoids: WGS 84, GRS 1980, Clarke 1866, International 1924, Krassowsky 1940, Airy 1830, Bessel 1841, Clarke 1880) and the WGS 84 datum ship as defaults you may
extend or override.
What is not served. Of the 5 363 projected systems in the current EPSG dataset the engine serves 5 349 (99.7 %), 41 of them on a prime meridian other than Greenwich. The other 14 use 10 methods it does not have: Bonne South Orientated,
Polar Stereographic variant C, Laborde Oblique Mercator and the Transverse Mercator zoned grid (two each); and Hyperbolic Cassini-Soldner, Transverse Mercator 3D, Local Orthographic, the Tunisia mining grid, Lambert Conic Near-Conformal and the New Zealand Map Grid
(one each). A system with one of these is skipped by tools/crs/build_crs_definitions.py, with the reason, and refused by the engine, naming the method - never approximated.
Datums. Moving between systems on one datum needs nothing more. Between two datums it needs each datum's transformation to WGS 84 (mapping.datums.<name>.toWgs84: seven
parameters, position-vector or coordinate-frame convention). Without one the conversion is refused, naming the datum - guessing a datum shift would put a well hundreds of
metres from where it is. Grid-based shifts (NADCON, NTv2, OSTN and the like) are not supported; a Helmert transformation is accurate to metres at best, which is the price of using one.
A map position has no height, so a shift assumes the ellipsoidal height of the source position is 0: tens of metres of real height change the result by millimetres.
Krovak Modified has a published worked example, and the engine reproduces it (latitude 50 12 32.442 N, 34 30 59.179 E of Ferro gives southing 6 050 538.71 and westing 5 568 990.91, and back), a check independent of PROJ. The example also settled a point of data: the dataset gives the modified systems a co-latitude of the cone axis of 30 17 17.3 degrees, a rounding of the 30 17 17.30311 that the plain Krovak systems, PROJ and the example itself use - 3 mm at the cone's radius - so the generator uses the full value.
One system has a looser check, and says why. The Belgium method (EPSG:31300) is the one place PROJ cannot be the oracle: its pathway evaluates the method as a plain two-parallel Lambert and does not apply the 29.2985 arc-seconds, so it disagrees by 743 m with PROJ's own plain system EPSG:31370, which describes the same grid. The plain system is the oracle, and the vector file records it, with a tolerance of 5 cm: the dataset gives the two longitudes to 0.001 arc-second, which at the cone's radius of 5 400 km is 2.6 cm, so the two definitions are only the same grid to a few centimetres. Every other system is checked to a millimetre.
The methods added since the first version are checked against PROJ over every current EPSG system that uses them (the whole population, not a sample): 40 Albers, 38 polar stereographic, 24 Lambert azimuthal equal area, 8 Mercator, 28 Cassini-Soldner,
32 Hotine oblique Mercator and 4 Krovak systems - 174 systems, worldwide, both hemispheres and the poles - reproduce PROJ's coordinates to the millimetre, forward and inverse. Independently of PROJ, the tests check each projection's defining
properties: an equal-area projection's Jacobian determinant is the ellipsoid's own area element everywhere; a conformal one has orthogonal columns of equal scale (and the scale factor at a Hotine projection centre is the one given); the scale is 1 along a
standard parallel; Cassini-Soldner's central meridian is the length of the meridian, as numerical integration shows; a pole is the origin. wellbore-config convert is checked against PROJ in CI for one system of each family - the WGS 84 ones directly,
the national grids (Qatar, Michigan, Switzerland, the Czech Republic) from geographic coordinates on their own datum.
Checked against PROJ. Every coordinate system the 62 country presets cite (191 systems, 1 146 points across their areas of use) reproduces PROJ's coordinates, forward and
inverse, with a worst error of 10 nanometres, built from nothing but its definition; four datum shifts (three with all seven parameters) match PROJ's three-dimensional pipeline
to the millimetre. The azimuthal equidistant family adds nine: the seven Equi7 continental grids (test points up to 10 585 km from the origin) agree with PROJ to 2-4 nanometres forward and 1-25 nanometres inverse, Antarctica, a polar origin, to 0.5 micrometre (the meridian-arc series), Guam to 2 nanometres, and the Yap Islands to 0.14 mm - EPSG's series against the exact form PROJ uses for it, a difference that grows as the cube of the distance. The test suite keeps 308 systems (1 848 points) and their PROJ values; tools/crs/build_crs_definitions.py reproduces the full set.
Getting definitions. python3 tools/crs/build_crs_definitions.py 32638 28992 2154 > systems.json (or --presets for every code the country presets cite) writes definitions from
the EPSG dataset, with pyproj, as an environment file you can extends. The EPSG dataset has its own terms of use (https://epsg.org/terms-of-use.html), which you accept by
generating the file; no table of definitions ships with the library. Datum transformations are not written - they are your survey department's choice.
Converting. wellbore-config convert <environment.json> <from> <to> <x> <y> moves a position (a geographic system takes longitude, then latitude).
Not supported yet: the methods listed under What is not served - a definition naming one is refused; vertical datums.
Contour maps
Contouring.Trace(grid, valueUnit) draws the contour lines of a surface by marching squares: linear interpolation along the cell edges, the two saddle cases decided by the mean of the four
corners, and cells touching a blank (masked) node skipped, so a line ends at the mask instead of crossing it. Lines come back as polylines, closed or open; a level that equals node values
exactly (round depths do) gives a line through the nodes without repeated points. The levels are multiples of the interval that lie strictly inside the range of the values.
ContourMapView draws the map on the shared drawing layer: the fill, the contours, the wells (MapWell), axes, a legend, a scale bar and a north arrow, with north up and the two axes at one
scale. MapExport.ToSvg, ToPdf and ToPng write it (PNG at printing.dpi). Every choice is the environment's:
| Setting | What it decides | Default |
|---|---|---|
mapping.contourInterval |
the interval; a length unit is converted to the map's unit, an empty unit means the map's own. None: a round interval (1, 2 or 5 times a power of ten, Heckbert 1990) | none |
mapping.targetContours |
about how many lines an automatic interval gives | 10 |
mapping.indexContourEvery |
every n-th contour is heavier and labelled; 0: none | 5 |
mapping.contourLineWidth, indexContourLineWidth |
line weights, in points | 0.75, 1.5 |
mapping.contourLabelMinLength |
a contour is labelled only if this many label widths long | 3 |
mapping.colorRamp, reverseColorRamp |
the fill colours, low to high (#RRGGBB), and their direction |
viridis |
mapping.fillStyle |
bands (filled contours: one colour between each pair of contour levels) or cells (each grid cell in the colour of its value) |
bands |
mapping.colorSteps |
distinct fill colours of the cell fill (a banded fill has one colour per band) | 64 |
mapping.labelClearance |
room, in points, kept clear round every label | 2 |
The theme, the locale (locale.culture formats every number, not the machine's), the labels (mapping.*, view.contourMap) and the units come from the environment too; the scale bar uses metres
and kilometres, or feet and miles when the depth unit is feet. Viridis is the default because it is perceptually uniform and readable with colour-vision deficiency.
Filled bands. By default the surface is filled as filled contours: the region between each pair of contour levels is one colour, the ramp's colour at the middle of the band's range, and the legend bar is made of the same bands. A band is exact
geometry, not a picture of cells: each grid cell is four triangles round its centre (the mean of its corners, the rule that settles a saddle in the contour lines), the surface is the piecewise-linear interpolation of them, and every cell that crosses a level
is cut at it by linear interpolation. The bands tile the unmasked part of the grid exactly (the tests check the areas against a plane, a paraboloid's disks, and the area a contour line itself encloses), Contouring.Bands returns them, and a band is
drawn as a single path, so the pieces that abut leave no seams. fillStyle: cells keeps the earlier fill, a rectangle per run of cells.
Labels keep apart. The labels are laid out before anything is drawn. The symbols of wells and bubbles are fixed first; the index contours' labels come next (the longest lines first, the middle of the line first, then other places along it, and a label with
no clear place is left off rather than laid over another); then the labels of wells and bubbles go round their symbols - to the right, else the left, above, below - in the first place that is clear of every symbol and every label already placed and
inside the map. A well keeps its name even when nowhere is clear. mapping.labelClearance is the room kept round each, and ContourMapView.LabelBoxes tells where every label of the last drawing went. A well label sits on a plate so it reads on any
fill, and a labelled contour is broken under its label, as on a printed map. When there is no fill there is no colour bar, only the interval and the unit.
Maps from well data
WellMaps turns wells into the points of a map; each call returns a WellMapSet: the points (Points(), for gridding), the wells as symbols (MapWells()), and a table (Rows, ToCsv())
that says where every well's point came from - and why any well was left out.
var set = WellMaps.Structure(wells, "Top Alpha"); // or Thickness(wells, upper, lower), NetPay(wells, zone), Values(wells, w => ..., unit, text)
var grid = Gridding.Run(set.Points(), GriddingMethod.MinimumCurvature).Grid;
var map = new ContourMapView { Surface = grid, ValueUnit = set.ValueUnit, Title = set.Description }; map.Wells.AddRange(set.MapWells());
Where a point is. A pick is placed where the well really is: the wellhead plus the trajectory's offsets at the pick's measured depth, with the survey's azimuths brought to grid north
(magnetic: plus the declination, then minus the grid convergence; true: minus the convergence; the sign convention is survey.gridConvergencePositiveEast). A deviated well's pick can lie
kilometres from its wellhead, and the map shows it there. A missing declination or convergence is said in the table and the azimuth left as it is - not guessed. The wellhead's latitude and
longitude are WGS 84 unless the header's Crs names a geographic system defined in mapping.coordinateSystems (a datum shift is then applied), or says WGS 84 (EPSG:4326, WGS84, CRS84).
Maps are always in metres, even if their coordinate system is not.
The maps. Structure: the depth of a top, by mapping.structureDepth - tvdss (the default: true vertical depth below sea level, from the depth datum's elevation), tvd or md. Thickness: the
true vertical thickness between two tops (an isochore: the true vertical depth of the lower minus the upper), placed midway between the two picks; a true stratigraphic thickness (an isopach)
would also need the dip, which is not applied (below 5 degrees of dip the two differ by under 0.4 %). A thickness that is not positive is kept and noted: the picks are out of order, or a fault cuts the
interval. NetPay: the pay summary's net pay in true vertical thickness for a zone, at the middle of the zone. Values: anything per well - an average porosity, an initial pressure, a cumulative
production - at the wellhead (a pressure map has no datum correction: give the value already corrected). Grid.Minus also subtracts two gridded surfaces. Tops are found by name ignoring case,
spaces and punctuation; several picks of one name use the shallowest, and the table says so.
A well that cannot be placed is left out, with the reason (no wellhead position, no survey, no elevation for the depth datum or one measured from ground level, no pick of that name, a coordinate
system not defined here), never guessed - except where you say so: mapping.assumeVerticalWhenNoSurvey takes a well with no survey as vertical, mapping.assumeWgs84WhenCrsUnknown takes an unknown
Crs as WGS 84. A value at the wellhead needs neither survey nor elevation.
mapping.mapCoordinateSystem names the coordinate system of the map; without it the map uses the UTM zone of the centre of the wells (the standard zone, without the exceptions of southern Norway
and Svalbard), and says so if the wells reach beyond that zone's width - name a system for a field that straddles zones.
Bubble maps
ContourMapView.Bubbles draws a value per well as a bubble, over a surface or on its own (the map's extent then comes from the points). The area of a bubble is proportional to its value: the
largest value has the radius mapping.bubbleMaxRadius (16 points), and no bubble is smaller than mapping.bubbleMinRadius (2) so a small value stays visible. A negative value is a ring, of the size its
magnitude gives. The key beside the map shows three sizes and states the rule. Large bubbles are drawn first, so a small one is never hidden under a large one.
Limits. A well labelled with nowhere clear (ten wells on one spot) overlaps its neighbours rather than lose its name; a contour label with no clear place along its line is omitted.
3D scenes and glTF export
A Scene3D holds surfaces (AddSurface(grid, depthUnit, name): depths below sea level, converted to elevation in metres), well paths (AddWells(wells, planned): from the wellhead to the total depth, placed exactly as
the maps place them - the same coordinate system, survey and north handling, and a well that cannot be placed is left out with its reason in Notes) and picks (AddPicks(wells, topName)). Everything shares one frame:
X east, Y north, Z up, in metres, in the coordinate system of the first wells added. Scene3DView draws it on the shared drawing layer, in software (no GPU), so it runs anywhere the 2D views run.
Controls. Drag turns the scene, the wheel and a pinch zoom, a two-finger drag pans; the arrow keys turn it (with Shift they pan), plus and minus zoom, Home frames the scene. Camera3D is the camera: an azimuth (the
compass direction it looks toward), an elevation (90 looks straight down: a plan view, east right and north up, exactly the 2D map's layout), a distance, perspective or orthographic (the same size at the target, so
switching does not jump). The view describes itself to assistive technology.
| Setting | What it decides | Default |
|---|---|---|
mapping.verticalExaggeration |
scales elevation (the view says when it is not 1) | 1 |
mapping.wellPathStep |
spacing of points along a well path | 30 m, or 100 ft in a feet environment |
mapping.maxSurfaceCells |
the most cells a surface is drawn with (a finer grid is thinned by a whole stride; the export keeps every cell) | 40 000 |
mapping.surfaceOpacity |
below 1 the wells behind a surface show through | 0.85 |
mapping.lightAzimuth, lightElevation |
the light: north-west at 45 degrees is the cartographic hillshade convention | 315, 45 |
mapping.fieldOfView, projection |
the camera | 35, perspective |
mapping.wellLineWidth |
line weight of a well path | 2 |
Surfaces are lit quads (ambient 0.3 plus 0.7 diffuse from the normal, which is turned to face up so the lighting does not depend on the side you look from), sorted far to near with the wells and picks: the painter's algorithm. A planned well is dashed. Because the sorting is per piece, two surfaces that cross each other, or a well that pierces a surface, are right only to the size of a cell or a path step; a translucent surface shows faint seams between its cells.
glTF 2.0. SceneExport.ToGlb writes a .glb (and ToGltf a .gltf with its data embedded) for any viewer: surfaces as triangle meshes with normals and vertex colours (the colour ramp, in linear light as glTF requires),
well paths as line strips, picks as points. glTF is right-handed with Y up, so X is easting, Y elevation and -Z northing. Coordinates are written relative to the scene's centre - a UTM easting of millions would lose its
millimetres in 32 bits - and the root node's extras give the centre, the coordinate system and the exaggeration; the exaggeration is the root node's scale, so the vertices stay true. A cell with a blank corner is left out.
Names, the planned flag and the pick labels are in the nodes' extras (glTF has no text).
The export is checked three ways: by the tests against the data; by the Khronos Group's reference validator on every file the tests write (tools/ci/gltf-check.sh: no errors and no warnings); and by loading a file in an
independent viewer (three.js), which shows the same map as the 2D view with north up and east right - a validator cannot tell a mirrored model from a correct one.