Getting started
Opening a raster
Toolbar folder glyph · File ▸ Open
The toolbar's folder means
“bring this into the image I am looking at”: one raster becomes a layer
over the current image, and several ask whether to layer them or combine them into
one all-band image. File ▸ Open makes a new window. Files can also
be dragged onto the window, and a file the app is launched with takes the same
door as any other.
A satellite product (Landsat MTL, Sentinel-2 SAFE,
Maxar IMD/RPB, Airbus DIMAP v2, SPOT Scene in DIMAP v1, NITF) is a multi-band stack
with an import plan, and it always opens its own window. A raster that cannot be
aligned with the current image also opens its own window, because a failure would
have nowhere else to go. Recognition of a delivery looks at most one folder below the
one it was handed. A downloads folder is never mistaken for a delivery inside
it.
Opening a delivery that has more than one grid
Asked on open
A satellite scene routinely ships several resolutions over the same ground: Landsat 7
delivers six 30 m reflective bands, two 60 m thermal bands and a 15 m panchromatic
band. Those cannot become one raster without resampling, and nothing is resampled on
open. The grids are kept separate, and each is described by band count, pixel
dimensions, ground pixel size and sample type. Each grid has a tick. A popup over
the ticked rows chooses which becomes the window's base. The rest arrive as layers
over it in the same window, each at its own native resolution. Open is refused
while nothing is ticked.
Every readout, every polygon and every
processing target is expressed in the pixel grid of the base. That choice is left to
you. The sample type is part of each row's description because it makes a grid a
different grid. Landsat 8's solar and view angle bands are Int16 on the same 30 m
grid as the UInt16 reflectance bands. Without the sample type, the two choices would
read identically.
A row starts unticked when the files behind it are
named for a browse or branding image and the grid is a sixteenth or less of
the largest in the selection. Both conditions have to hold. A folder of nothing but
quicklooks stays ticked, and a full-resolution raster called PREVIEW.TIF
is never unticked for its name. The row says why it started that way. Two
ungeoreferenced rasters of the same size are one grid only when they sit in the same
folder. That is the only evidence such files can offer that they belong
together. Grids that do not cover the same ground open as separate projects in the
one window, each with its own coordinate system.
Opening a folder
File ▸ Open, or drag the folder onto the window
The folder is walked and every raster it holds is offered as one selection, with the
same Layers-or-Combine question a multi-file open asks. There is no limit on how many
may be opened. Tiles that sit side by side combine into one image, and a survey folder
of 92 orthophotos becomes a single mosaic over the whole extent. The one ceiling is on
walking the tree, at 4,096 files. When it is reached, the count is reported as a
floor.
A folder may hold both a container and the files that
container reads: a .vrt stack written beside its own band
files, or a Maxar .til beside its tiles. The container is kept
and its sources are dropped from the selection. Each measurement is then counted once in
every band list and every band-math expression. Those bands are still present through
the container, and each one still names the file its pixels came from.
What happens on open, and what does not
Automatic
Nothing is corrected on load. The default stretch is Original, the band's full
range, and no calibration, mask or resampling is applied. The catalogue reports
what conversions the delivery offers. Applying one is an explicit act.
A raster without overview pyramids still opens
at once, streaming from full resolution. A non-modal banner offers to build a
compressed sidecar in the background, with a remember-my-choice option. Nothing is
written beside your data without consent.
Splitting a stack into layers, and combining layers into a stack
Right-click a raster in Layers ▸ Split Bands into Layers · Combine Layers into Composite
Split turns a multi-band stack into one layer per chosen band, for when bands need
separate display settings or separate processing. Combine is its inverse. Single-band
layers sharing an exact grid become one composite by reference, with no pixel copied.
The bands are ordered red, green, blue, near-infrared and then by wavelength, the same
rule the import uses. A split-and-recombine round trip lands each band back in its slot.
Several single-band files opened at once get the same
Combine prompt. A band split out of an image inherits the image's own verdict on
whether it is an elevation model. A channel of an aerial photograph is never
offered a slope.
The Organiser
Window ▸ Organiser · ⌥⌘O
A window over the imagery you have. It lists every raster in your Workspace folder and
any folder you add, with a thumbnail, a name and the facts that decide which scene you
want: satellite, level, date, format, grid, bands, CRS, pixel size and size on disk.
A delivery is one row read from its manifest. Loose band files of one scene regroup
into one row per grid. Rows appear before they are described and the sidebar counts
how many have been read. Sort and filter from the toolbar. Double-click a row to open
it, through the same preflight a File ▸ Open would give it.
Every value is badged with its
source. Manifest and GDAL readings are plain. A value taken from the filename wears
the amber badge, because a filename is a hint where a manifest is a statement. The
thumbnails and descriptions are cached between launches under a byte cap set in
Settings ▸ General. The cache is keyed on the describing code as well as the file, and
a newer build never serves a description written by an older one.
GuideRail
Help ▸ GuideRail · ⇧⌘G
A window of step-by-step rails through the longer tasks: a proximal survey to soil
pits, a property's carbon-forestry baseline, change between two dates, an
unsupervised land-cover map, a DEM to a draft Land Resource Inventory, raw numbers to
comparable reflectance, taking sensor striping out, several scenes into one mosaic,
sharpening coarse bands with a finer guide, and finding and downloading the right
scene. A shelf of cards shows each rail with a miniature of its progress. Open one and
the steps run along a traverse, with the current station ringed. Every step names the menu
its controls are under.
Ticked steps fold away and future ones are sealed. The
current step is always the first unticked one, and ticking ahead cannot skip work.
Ticks persist between launches. Where Apple Intelligence is available, a More info
button expands a step from the app's own guide text under instructions that forbid
adding to it. Elsewhere the authored text is the whole feature.
The window
The Layers sidebar
Left sidebar glyph in the toolbar · ⌘0
Every raster, vector overlay, polygon and annotation layer in one drag-reorderable
tree, with groups. Each row carries a visibility toggle, an opacity slider and a
blend mode. The base raster is a member of that stack like any
other, and a layer can sit below it. Clicking a layer's name makes it the active
layer, marked with an amber scope glyph. The active layer is the target for
processing, for the Bands panel and for the readout. Right-click for Rename, Remove, Save As GeoTIFF, Copy,
Open in New Window, Use as Processing Region, Relief Shading, View in 3D, and the
elevation-model statement.
Layers that cannot share a grid group into
projects by coordinate reference system, each labelled with its CRS. A layer in
another CRS is drawn in place through an on-the-fly transform. Reprojecting is only
needed when a file on the target grid has to be written. Each raster row also carries
its value distribution as a sparkline. The sparklines are how the one layer in twelve
whose histogram sits somewhere different is spotted before it becomes a seam.
A raster is recognised as an elevation
model from its own evidence and labelled with a question mark where the file never
said so. The row offers “Treat as Elevation Model” or “Not an
Elevation Model”, whichever would change something, and the statement is kept in
the project.
Blend modes on layers and groups
Layers ▸ the picker beside each opacity slider
Normal, multiply, screen, overlay, soft light and luminosity, the six ISO 32000
modes, on any raster layer, blended in the same render pass as everything else. A
group has its own picker. Pass through leaves the group as a folder
whose opacity multiplies into each child. Any mode composites the group's layers
into one picture first, then blends that picture over the frame at the group's
opacity. Those are different images: white in multiply inside a group at 50 % over
grey reads 0.5 as pass-through and 0.75 as a picture.
A blend is display compositing. Nothing blended
can leave as a raster. An export takes the layers' own samples. A preset can put a
levels cut on a group, and there is no control for that cut yet. The group row's
subtitle names the cut, because the row has to describe what the map draws.
The Info inspector
Inspector ▸ Info · ⌘6
Categories covering georeferencing (CRS, pixel and ground size in the CRS's own
units), sensor identity and the resolved calibration profile, acquisition date and
sun geometry drawn on a sky dome, the composite's source file and band for each
slot, applied display geometry such as crop and rotation, raw metadata, and a System
category showing the GPU, memory gauges and streaming state.
Rulers, scale and readout
Ruler glyph in the toolbar · the footer bar
The footer is the instrument panel: cursor coordinate, pixel values, display scale
as a percentage where 100 % is 1:1, the scale bar, and an SDR/HDR badge with the
display's EDR headroom. The coordinate's decimals follow the pixel size: six over
10 cm imagery and four over a kilometre. Its context menu switches between decimal
degrees and degrees-minutes-seconds. Right-clicking the map copies the clicked
coordinate as signed decimal degrees, the form other tools accept when pasted. Rulers
draw along the top and left edges. A ruler labels one axis along a screen edge, which
only holds while the two are parallel, and the rulers switch off while the image is
rotated.
Map Overview
Inspector ▸ Map Overview · ⌘8
Where the scene is, on a basemap. Every raster in the window is drawn as a
footprint, and the pane follows the active project. A zoomed-in view still says
which coastline, city, river or lake it is over. It draws from a national tile
service where one covers the ground (LINZ, USGS, swisstopo, IGN) and falls back to
Apple's own basemap where none does. The pane says which it is showing. It also says
when it has magnified past a service's deepest tiles.
The overview is for finding a place, and its map
carries no measurement of your data. Every other inspector category describes the
pixel, and this one describes the ground. It is the one category a click on the raster
will not switch away from. Panning it by hand turns following off. Switching to another project turns
it back on.
Vector overlays
Inspector ▸ Overlays · ⌘4
Shapefiles, GeoPackage, GeoJSON, KML and KMZ open as overlay layers drawn in the
raster's own coordinate space, alongside the polygons you draw, imported point layers,
GCP markers, classification results and annotation notes. Each is its own layer: hide
it, fade it, reorder it, or flag it Use as Processing Region so that
region-aware jobs clip to it exactly as they clip to selected polygons.
A vector file in a different CRS from the raster is
transformed for drawing. That is a display transform and writes nothing. A shapefile
whose .prj was not granted alongside it cannot be placed at
all. The Workspace prompt is there for that case.
Every vector layer draws its lines and its point dots
at a width held in screen points. They look the same at every zoom. Right-click
the layer's row for Line Width… or Point Size…: a slider each, with
the value read out, and the map follows the thumb.
Trap.NZ projects: boundary, lines and traps by last check
Trap.NZ menu · Settings ▸ Trap.NZ
A Trap.NZ project is drawn over the open image as one group of layers from its map
feed: the project boundary, its lines in the colours the project gave them on
trap.nz, and its traps coloured by how long since each was last recorded against.
Click a trap for its callout: code and line, type, last record with the days,
installation, tags, sensor, notes. Shift-click to add another, and click the dot again
to put it away. The menu's Show Details for All Traps tick draws all of
them for a figure. Unticking it puts every callout away. Retired traps are counted in
the banner and not drawn. The bands are the calendar's: within a week, a fortnight, a
month, two months, a quarter, half a year, longer, and never recorded. The Overlays
inspector draws the legend as a bar per band by count, on the colour strip, over a
scale of days. Showing a project again refreshes it in place. Lines
and dots arrive at a width made to be seen. The row's Line Width and Point Size
sliders change either.
Setup is a key and a list. Generate a map-feed key under My account on
trap.nz and paste it into Settings ▸ Trap.NZ. Then add projects by id. The id is the
number at the end of the project's address, https://trap.nz/node/123456.
Alternatively, let Look Up My Projects list the ones your account belongs to.
The key is read-only, kept in your keychain and sent only to io.trap.nz. Because
Trap.NZ carries the key in the feed's address, it is never written to a cache.
The feeds are rebuilt overnight. A check made
today shows tomorrow, and the legend says so. Trap.NZ gives the same empty answer for a
wrong key, a wrong id and a project your account is not in, with no error. Hachure
refuses to draw an empty project and says which three things to check. The colours
are true on the day they were computed. On a project file reopened later, the
inspector offers Recolour for Today, which Trap.NZ ▸ Recolour Traps by Last
Check also runs. Contact details the feed carries for a trap are not brought into the
layer.
Elevation profile
Toolbar profile glyph
Draw a line across an elevation model and the pane charts what is under it: distance
along the ground on one axis, the surface's own height units on the other. Because a
profile has to say which surface it measured, it is offered only when the active
layer holds heights.
The active layer is not marked as an elevation
model. Right-click its row in Layers to say that it is. The footer reports the height
under the cursor from any DEM in the stack. That is the quicker check.
View in 3D: an image draped over its elevation model
Right-click an image layer ▸ View in 3D…
Drapes the layer over an elevation model in the same window, under an orbit camera,
with vertical exaggeration on screen. The DEM is chosen by the most ground it shares
with the image. Where the image reaches less than all of the surface, the menu
item's help states the share, rounded down. The image lands at its true ground
position and scale whatever its bounds are.
Ground the image does not reach is
transparent. Unlit black would read as real surface, and a third of a hillside would
look like night. A nodata gap inside the image is a hole for the same reason.
The same command on an inverted proximal survey
opens the volume view described under Proximal survey.
Crop
Crop glyph in the toolbar
Drag a rectangle over the active layer to keep. Shift squares it. The marquee snaps
outward to whole pixels of the layer being cut. A marquee dragged around something
keeps everything it enclosed. Cropping again intersects with the existing window. It
is display geometry. No sample is discarded, and ⌘Z undoes it. It carries through to a
GeoTIFF export as a source window, and the written pixels are the file's own.
Rotate
Rotate glyph in the toolbar
Drag the dial to turn the active layer to any angle, 0 to 359 degrees clockwise. No
pixel is resampled. Rotating the base raster turns document-pixel space itself.
Polygons, imported vectors and annotations follow the imagery they were placed on.
Info states the offset from the source in the file's own pixels.
Comparing two rasters
Split-rectangle glyph in the toolbar
The base document is A and any added or derived raster is B. Four modes: fixed side
by side, a draggable swipe, a linear A/B blend, and timed flicker. All are
display-only and isolate A and B from the rest of the stack. Pressing the glyph
again stops comparing.
Separately, up to four named view groups link camera,
zoom and crosshair across windows, using geographic coordinates where both datasets
have a CRS and normalised image coordinates where they do not.
Notes and callouts
Speech-bubble glyph in the toolbar
Clicking the image drops a callout: a dot pinned to that pixel and a text box
standing off from it, joined by a leader line. The dot is held in image pixels and
stays on its feature through pan and zoom. The box keeps one readable size at every
zoom. The distance between them is never a ground measurement.
Selecting a callout shows a style bar with five colours: box outline, box fill, line
and dot, text, and a highlight behind it.
Callouts burn into a rendered PNG, HEIC or OpenEXR
export. A GeoTIFF writes measurements and leaves them out. Save the window as a
project to keep them.
Ask about the scene
Inspector ▸ Assistant · ⌘7
An on-device assistant for questions about remote sensing, the sensor catalogue and how
this app does things: which bands make a natural-colour composite of the scene in front
of you, what separates NDVI from NDMI, how to pan-sharpen. It runs on Apple's on-device
model, and nothing leaves the Mac. Each answer names where its facts came from.
The assistant is handed a description
of the scene's metadata. Because that description has nowhere to put a pixel, the
assistant cannot read your data, compute a statistic or run a job. It can say which
band is red. It cannot say what that band reads at a point. Where the on-device model
is unavailable, the panel says so.
Bands & display
Choosing which bands are Red, Green and Blue
Inspector ▸ Bands ▸ Composite · ⌘1
One row per band. Each row's three dots put that band in the red, green or blue
channel, and clicking what the row says the band is lets you correct or supply it.
Above the list, presets (True colour, Colour infrared, SWIR, Agriculture, Geology)
are each drawn as a small spectrum showing where their three bands sit. A preset
whose bands the image lacks draws them hollow, and the reason it cannot apply is
visible. Where bands state their wavelengths there is a spectrum strip whose R, G
and B markers drag along it, or step band by band with the arrow keys.
All of it acts on the active layer, the one marked
with the amber scope glyph in the Layers sidebar. Where the bands state no wavelength,
as in a photograph, the axis stays and says so across it. The band list does the
assigning. The catalogue identifies a band by its description, its filename or its
position in a known layout. A band it has identified takes the catalogue's role
over the file's own colour interpretation.
Display stretch and contrast
Inspector ▸ Bands ▸ Stretch
Original (full range), percentile clip, manual low/high, and empirical-CDF histogram
equalisation, each with gamma. The default when an image opens is Original.
Stretch is a display exposure only. It
never changes stored values. Processing jobs, band maths and the GeoTIFF export all
read source samples regardless of what the screen is showing. The one way to get
the curve into a raster is to ask for it by name: Processing ▸ Radiometry ▸ Apply
Display Tone Curves. It writes a new file and labels it as display intensities.
Histogram
Inspector ▸ Bands ▸ Histogram
Bins the shown bands over one shared domain so the channels can be compared. Scope
switches between the viewport and the whole image. For integer data a bin is a whole
number of values wide, and a gap means no pixel holds that value. The bars are drawn
as steps because a histogram is a count over a range.
While a transfer is set (levels, a curve, or any stretch other than Original) a
second, fainter trace is drawn over the first. It shows where that transfer sends the
counts: how much of the output range the setting is using, and whether it is
clipping. The input distribution alone cannot say either. Because a bin is an
interval, each one's counts are spread across the output interval it lands on. The
ghost is therefore smooth, where a naive mapping would comb into spikes at the
values the transfer happens to hit.
Original draws no ghost. It is the state a scene opens in, and the solid trace
already stands for it. It is also not the identity. Original maps the storage type's
whole range. A 16-bit file holding Landsat values between about 7,000 and 30,000 uses
barely a tenth of the display under it, while a neutral Levels or any authored
stretch uses nearly all of it. That is where the large brightness jump on switching
away from Original comes from. The ghost matters because, on a normalised value axis,
two linear transfers differing only in scale draw exactly the same shape, however
different the picture looks.
Export Histogram writes the bins and counts as CSV.
Auto Contrast and Auto Colour place the levels for you from the current scope. Auto
Colour works per channel and will shift colour balance deliberately.
Levels and Curves
Inspector ▸ Bands ▸ Levels · Transfer
Black point, midtone and white point per channel, and a freehand transfer curve under
the same histogram: click the curve to add a point, drag to shape it, double-click a
point to remove it. From Equalise seeds the curve with the shape
histogram equalisation would produce, then freezes it. Equalisation recomputes as the
view moves. A curve does not, and it can be carried to another scene. Straighten returns it to the identity.
Both act on the raster selected in Layers,
which the section header names. Both are display exposure only. Nothing stored moves.
To get the curve into a file, ask for it by name: Processing ▸ Radiometry ▸ Apply
Display Tone Curves.
The plot's axis is trimmed to the values in view. The
five handles are placed on that axis and land over the range the data
occupies. A colormap ramp can be reversed from the same section, and the direction is
saved.
Relief shading a DEM
Right-click an elevation layer ▸ Relief Shading…
Offered when the layer is recognised as an elevation model. An illumination dial
(the handle is the sun's position on the sky dome seen from above, centre overhead,
rim at the horizon) with vertical exaggeration, multi-directional light, cast
shadows, skylight, and a hypsometric, slope or aspect tint over any colormap. A live
thumbnail follows every control. The full-resolution pass runs only on Apply.
Because the shading is a picture, it stays
display-only and cannot leave as a raster. The measurements are Processing ▸ Analysis ▸
Slope and the terrain products listed under Terrain products. Those write every light
and every horizon as a band.
Raster expression, drawn live
Inspector ▸ Bands ▸ Raster expression
Compiles the same expression language as Band Math to a Metal shader at runtime and
draws the raster you are on as it, false-coloured through a colormap with a legend.
Display only, no file. Use it when what you want is a look, and Band Math when you
want a layer.
Reflectance transformation imaging
File ▸ Open a .ptm or a .lp light file · Inspector ▸ Bands ▸ Relight
A reflectance transformation image holds, per pixel, a function of the light direction
in place of a colour. A rock art panel or an inscription photographed under a dome
of lights can be lit from any side afterwards. Open a polynomial texture map
(.ptm, in the LRGB or the RGB layout) and it converts on the
way in and opens relit. Open a .lp light file and the window
of its first photograph offers to fit one from the whole capture, in Malzbender's
biquadratic polynomial (six terms, one colour or per channel) or in hemispherical
harmonics to order two or three (nine or sixteen terms per channel). The fit runs in
the Jobs panel. Its result opens as its own window, with the surface normal from
photometric stereo beside the coefficients.
The Relight section sits first in the Bands inspector for such a
raster: the same dial as the relief shading, azimuth and elevation, and the mode.
Relight evaluates the function under the light. Specular
enhancement adds Malzbender's highlight from the stored normal.
Diffuse gain scales the polynomial's curvature about its own maximum
to deepen relief. It is a polynomial-only mode. Normals draws the
surface normal as a colour. A light change is a uniform write and a frame. The light
and the mode are saved in the project.
Every photograph must be the same frame from the
same camera. The fit does not align them. Shadows and highlights are fitted like
everything else. A pixel dark under half the lights fits a darker function. Diffuse
gain at three under a 20° light takes a flat panel to black, because tripling the
fall-off reaches zero well before the horizon. Raise the light or lower the gain. The
converted copy of a .ptm and a fitted raster are written under
Application Support ▸ Hachure ▸ Reflectance imaging. Nothing lands beside the
photographs, and the alert says where. CHI's .rti layout is behind a
registration wall and is not opened.
Polygons & processing regions
Drawing and using a region
Pentagon glyph in the toolbar
One control, five ways of making a polygon: Click Corners (double-click
or click near the first corner to close), Free Draw (hold and trace,
closing when you let go), Rectangle, Ellipse, and
Select Similar Pixels, which lets the image decide where the edge is.
The tick in the menu marks the live mode. Unticking it puts the tool away. Each polygon
becomes its own layer, carries its ground area, and can be renamed, given a colour,
edited vertex by vertex, or saved as GeoJSON. Marking one Use as Processing
Region limits jobs to it. Region polygons draw in graticule cyan.
An imported shapefile or GeoJSON polygon layer can be
used as a region directly, with no conversion. A pixel belongs to the region when its
centre falls inside, under the even-odd rule.
Select Similar Pixels
Polygon glyph ▸ Select Similar Pixels
Press a pixel and drag away from it. The circle that opens under the pointer sets how
much ground the selection may cover. It also sets how much of the range around that
seed pixel counts as similar. Both widen the further you drag. What grows inside it,
four-connected back to the seed, is drawn as a dotted outline while the button is held.
Letting go commits that outline as one ordinary polygon, editable, nameable and usable
as a processing region like any other.
Match pixels by has two settings, and they are different measurements.
Value is how far the numbers are apart, scaled by each band's own
spread. It suits one band or a stack of one quantity: a DEM, a conductivity grid, an
index. Spectral shape compares the shape of the spectrum and ignores
brightness. Sunlit and shaded ground of one material stay together, and it is the
right choice for imagery.
The raster is read around the seed, and the read widens
as the circle grows. A region that runs off the edge of the screen comes back whole.
The drag itself re-grows from numbers already in hand, and that keeps it live.
Because the selection is grown from the seed, it
is always one connected region. It finds the paddock you pressed and stops at its
boundary. A class of every paddock like it is a classifier's job. The tool reads the
raster selected in Layers. An outline traced from one raster and committed onto another
would be wrong in a way nothing would show, and changing that layer mid-gesture cancels
the gesture.
Clip to a polygon
Right-click a polygon ▸ Clip
Keeps the image inside or outside a polygon and makes the rest nodata. The inside
case crops to the polygon's bounding box. The result is the shape and its
surroundings, with no black expanse.
A rectangular window with no polygon is Subset.
Radiometry
Radiometric Calibration
Processing ▸ Radiometry ▸ Radiometric Calibration…
Materialises the provider's own calibration equations, the ones the delivery
publishes, turning digital numbers into radiance, reflectance or brightness
temperature. Scale and offset in both conventions, solar-elevation reflectance,
Planck brightness temperature, Sentinel quantification, Maxar gain and bandwidth,
DIMAP divisor gain, and lookup tables. Per-band quantity, units, equation and
coefficient provenance are written into the result and shown in Info.
Only the operations you tick are applied, and
nothing is clipped, stretched or masked afterwards. A fill value or an out-of-range
input becomes NaN. A plausible number in its place would be the harder error to
find.
Atmospheric Correction · Dark Object
Processing ▸ Radiometry ▸ Atmospheric Correction…
Estimates the atmospheric path radiance from the darkest pixels in each band and
subtracts it. The scene percentile, the bounded estimation sample and whether
negatives are clamped are all yours to set. The output identifies the estimated dark
value and states explicitly that no mask was applied.
Dark-object subtraction assumes somewhere in the
scene is genuinely black in every band. Over a bright arid scene or a small subset,
that is often false. A full radiative-transfer correction in the manner of 6S is
not implemented, and the output does not claim one.
Haze Reduction · Thickness Map
Processing ▸ Radiometry ▸ Haze Reduction (Thickness Map)…
Estimates haze per location from a locally searched dark-object field (Makarau,
Richter, Müller and Reinartz 2014), then subtracts it from each band scaled by how much
that band sees haze. Dark-object subtraction takes one value per band for the whole
scene. This takes a field, and haze that thickens across a scene is removed where it
is. The coarse fields are folded in one streamed walk and upsampled per row inside
the transform. No full-resolution haze field is ever held, and a scene of any size
costs one row block.
It needs dark ground to find. Over a uniformly
bright scene (snowfield, desert, thick cloud) there is no dark object in a window, and
the estimate degrades. It refuses fewer than two stated wavelengths, because nothing
else can say which band is bluest. It also refuses when no valid pixels are found, and
refuses a haze trend broken beyond repair, naming the band. Departures from the paper are stamped
into the output.
Where haze is even across the scene, use
Atmospheric Correction (Dark Object).
Haze Reduction · Cirrus Band
Processing ▸ Radiometry ▸ Haze Reduction (Cirrus Band)…
Subtracts thin cirrus using the sensor's own 1.38 µm channel (Gao and Li 2017). At that
wavelength the water-vapour column absorbs all surface signal, and the band records
scattering alone. One relation is fitted per band for the whole scene. Every band of the
source is carried through whether corrected or not. The output is still the scene.
Offered only where such a band exists: Landsat 8/9
band 9, Sentinel-2 band 10 at Level-1C. It assumes the air above the cirrus is uniform.
A flat cirrus band is refused. A band for which no edge can be fitted is left
uncorrected and named in the result notice. Borrowing a neighbour's slope would be a
guess written as a correction.
This targets high cirrus. The thickness map targets
haze in the boundary layer. They are complementary.
Apply Display Tone Curves
Processing ▸ Radiometry ▸ Apply Display Tone Curves…
Writes the tone curves you are looking through into a new raster. Every display
channel is put through its own curve (stretch, levels, curve, histogram
equalisation, decibel, whatever is in force). The result is written as a
georeferenced GeoTIFF at full bit depth, either in the source's own data type over
that type's whole range or as Float32 from 0 to 1. The 4096-entry table the
shader samples is coarser than the data. The curve is evaluated per sample instead,
and the file comes out finer than the screen was.
Because a tone curve clips at both ends and is
not invertible, the result is not radiometry and cannot be treated
as any. Calibration, band maths, spectral indices and any physical quantity
computed from these numbers are meaningless. The measurements stay in the source,
which the output names. The file says so in its own metadata as well, and in a
per-band description ending “(not radiometry)”. An integer band cannot
hold NaN, and absent ground reading as legitimate black is a confusion worth a level.
Where a contributing band declares nodata and the output is an integer type, zero is
reserved for it and the tone occupies one level less.
Export as GeoTIFF writes the source's own samples
and records the curve beside them. The rendered exports (PNG, HEIC, OpenEXR) apply it
and produce a picture with no georeferencing. This is the middle case, with the curve
applied and the raster kept.
Topographic Correction
Processing ▸ Geometry ▸ Topographic Correction…
Removes the brightness difference between slopes facing the sun and slopes facing
away. Reflectance can then be compared across terrain. SCS+C, C-correction, Minnaert
with the constant fitted per band, and the statistical-empirical rotation. Sun zenith
and azimuth are auto-filled from acquisition metadata where the product states them,
and are editable otherwise. Slope and aspect come from a Horn 3 × 3 operator.
Needs a DEM covering the scene on its own grid.
A correction fitted where the DEM does not reach is not applied there, and the report
says how much of the scene was covered. It refuses to correct a DEM against itself,
and reports when the DEM is flat or does not overlap.
Geometry
Reproject
Processing ▸ Geometry ▸ Reproject…
Resamples the raster onto a different coordinate reference system, writing a new file
on the target grid. Every pixel is interpolated, and the output is a new set of
measurements. The result opens as a new document.
Choose the resampling kernel by what the pixels
mean. Averaging class numbers produces classes that are not in the legend, so use
nearest for a classification or any thematic raster.
A grid that crosses 180°
reprojected to a target that tears there (WGS 84 and Web Mercator both do) is refused
before anything is written. The panel names projected alternatives whose area of use
overlaps the scene. The refusal has a measured failure behind it. A naive bounding box
across the antimeridian is the whole globe, and a 2400 × 2400 MODIS tile at 463 m came
back as 3884 × 108 at twenty-two times the source posting, the data smeared into a
sliver. Both conditions are measured on your actual grid. A scene that merely reaches
180° without crossing, or one going to a local projected CRS, is untouched.
Because a layer in another CRS is already drawn in
place, reproject only when you need a file on the target grid.
Resample to Match Layer
Processing ▸ Geometry ▸ Resample to Match Layer…
Warps this raster onto another loaded raster's exact grid: same CRS, same extent,
same pixel size. The two can then be compared or differenced cell for cell. Nearest,
bilinear, cubic, cubic-spline, Lanczos, average or mode, chosen explicitly.
Use nearest for thematic data. Resampling a 30 m
DEM to 10 m makes the grids match and adds no detail.
Subset Bands / Extent
Processing ▸ Geometry ▸ Subset Bands / Extent…
Takes a spectral selection, a rectangular window, or both, and writes them out without
interpolating anything. Bands keep their source order and their values are the file's
own.
An irregular area is the polygon Clip command.
Ground Control Points
Processing ▸ Geometry ▸ Ground Control Points…
Fits a transform from points whose position you know in both images (affine, second-
or third-order polynomial, or thin-plate spline) and warps the raster through it. The
subject is the active layer. The reference is whatever is already correctly placed
beneath it. Each point is one feature clicked twice.
A third-order polynomial through ten points has
an in-sample residual near zero and can still be wildly wrong between them. Only the
held-out figure shows it. Read the leave-one-out RMSE.
Three commands align imagery, and each fixes a
different failure. Co-registration measures a whole-image shift
automatically and corrects nothing else. Reach for it first, because it costs no
clicks and most misalignment is a shift. Ground control handles
rotation, scale and local distortion, which a shift cannot. It costs placing
points by hand. Orthorectification is a different problem again.
Image-to-Image Co-registration
Processing ▸ Geometry ▸ Image-to-Image Co-registration…
Aligns this raster to a reference by measuring the shift between them with GPU phase
correlation, then warping once onto the reference's grid. Reports RMSE and peak ratio
before and after.
Translation only. A residual rotation or scale is
not corrected and will show as a shift that varies across the scene.
Orthorectification
Processing ▸ Geometry ▸ Orthorectification…
Removes the terrain displacement in an image taken at an angle, using the sensor model
the delivery carries (RPC or ground control points) together with a DEM. Target CRS,
pixel size, interpolation and maximum transformer error are all explicit.
Displacement is height times the tangent of the
view angle. At 27° off nadir a 1000 m hill moves its ground point about 510 m. Over
flat ground this changes very little. Over the Southern Alps it changes everything.
RPCs arrive with the delivery and cannot be made
here. Ground control can. Ground control plus a DEM is a genuine orthorectification.
Ground control alone only warps the image flat.
Pan-sharpen / Fuse
Processing ▸ Geometry ▸ Pan-sharpen / Fuse…
Injects the detail of a higher-resolution guide band into coarser bands. A
multispectral scene takes the sharpness of its panchromatic one and keeps its
colour relationships. Methods are SFIM, Brovey, GSA and MTF-GLP-HPM. A standard step
before segmentation, object-based classification and any work where the boundary
matters more than the pixel.
How faithful the fused values stay to the source
depends on the method. MTF-matched and GSA degrade the guide through
the sensor's own response before injecting it. That keeps the fused values
consistent with the source. Aggregated back to the coarse grid, the result should
reproduce the input. A plain component substitution holds that much less well. Where a
figure has to be defensible per pixel, compute it on the source bands and use the fused
product for the geometry.
Guide data decides what the detail is taken from. Band n
is the ordinary case for a panchromatic guide. Mean of all bands is the
cheap fallback. Fitted per band (least squares) solves least squares
from the guide's bands onto each coarse band, then applies those weights at full
resolution. Each guide band is first degraded the way the chosen method degrades its
guide. The third option makes fusion possible where no single guide band resembles the
band being sharpened. MODIS bands 1 and 2 at 250 m against the 500 m shortwave bands are
such a case. Snow is bright in red and dark at 1640 nm, and a single red guide injects
every boundary upside down. That is worse than not fusing at all. The fit is free to
weight a guide band negatively, and that case needs exactly this. It is offered for
SFIM and MTF-GLP-HPM only, and only when the guide has more than one band. GSA and
Brovey already fit or normalise a guide of their own, and a second fit underneath has
no meaning.
Because SFIM, MTF-GLP-HPM and Brovey scale every
band of a pixel by one common factor, they leave band ratios exactly as they were. An
NDVI or NDSI computed on such a product equals the index of the resampled coarse bands.
Computing it there gains nothing but a larger file. GSA is the one method of the four
that moves a ratio, because its injection is additive with a per-band gain. The sheet
prints this beneath the method picker for the three it applies to. Fuse for the
geometry, and compute the index on the source.
Because a coarser grid has no detail to contribute,
only layers finer on the ground than this one are offered as a guide. Fitting per band
costs reads. Each coarse band is fitted against the guide one band at a time, and the
guide cube is never resident. On a six-band Sentinel-2 20 m stack against its 10 m
bands, the fitted job runs in about 15 s and a single guide band in about 4 s.
Analysis
Band Math
Processing ▸ Analysis ▸ Band Math…
Combines this raster's bands into one new layer, as a named index resolved from its
spectral roles or as an expression you write. Presets cover NDVI, NDWI, NDMI, NBR, NDSI,
NDRE and tasseled-cap brightness, greenness and wetness, resolved against whatever
bands the image carries. A custom expression takes an arbitrary formula in
b1…bN with arithmetic, comparison, logical and bitwise
operators, conditionals, clamp, min and max, logarithms and QA bit extraction.
Expressions evaluate over the raw samples, and the result is a measurement.
An index is only as good as the roles behind it.
NDVI is computed from whichever bands are named NIR and Red in Bands ▸ Composite. On
a stack whose roles are wrong, it produces a smooth, plausible surface of the wrong
two bands.
Band Statistics
Processing ▸ Analysis ▸ Band Statistics…
Mean, standard deviation, minimum, maximum and optional percentiles per band, over the
whole image or a chosen region. For 8- and 16-bit storage the percentiles are exact and
come from the same pass as the moments.
Percentiles state their own resolution: exact for
integer data in a modest range, and a declared bin width for float data.
Zonal Statistics
Processing ▸ Analysis ▸ Zonal Statistics…
The same statistics, per polygon, in a single pass over the raster however many zones
there are. A pixel belongs to a zone when its centre falls inside.
A table quietly shorter than the layer it came
from is the kind of gap nobody notices. An empty zone keeps its row, with a count of
zero.
Principal Components / MNF
Processing ▸ Analysis ▸ Principal Components / MNF…
Principal components, or the minimum noise fraction, which is PCA after whitening
against an estimate of the noise. Both write one band per component.
MNF's eigenvalues are noise-adjusted and report
signal-to-noise. PCA's report variance explained. Only the second means
“how much of the scene is in this component”.
Decorrelation Stretch
Processing ▸ Analysis ▸ Decorrelation Stretch…
The ASTER AST06 colour enhancement. Three bands are rotated through the eigenvectors
of their correlation matrix, each component is stretched to the same spread, and the
rotation is undone. The colour axes stay where they were, and the correlation
between them is gone. Writes red, green and blue at the target mean and standard
deviation (127.5 and 50 by default, the ATBD's), uncorrelated. It is a visual aid, and
the values have no physical units. The sheet previews the stretch on the image as its
controls move, at every zoom, and writes nothing until Run. For a photograph the
stretch can work in YUV or L*a*b* in place of RGB, as DStretch's named enhancements
do. An emphasis wheel puts more of the contrast on one hue axis (reds and cyans, or
yellows and blues) or on lightness.
It exploits whatever differences the three
channels have, real or not. Where the scene variation is mostly noise, the result is
colourful and painfully noisy. A strongly bimodal scene gives less colour than one
whose values are near-Gaussian. Use three bands of one sensor at one pixel spacing.
JPEG stores chroma at half resolution per macroblock, and the stretch multiplies that
by tens. A JPEG source comes out blocky in colour. Shoot RAW or lossless.
The Statistics inspector gains a section with the fit's
means, spreads, eigenvalues and correlations, and a CSV of the full coefficient table.
A run that could not fill the colour space says so as a layer notice.
Endmember sets and spectral libraries
Inside Spectral Unmixing… and Spectral Angle Mapper…
Both commands work from a named set of reference spectra. There are two ways to get
one. Derive a set from the selected polygons takes the mean or median of
the pixels inside each polygon you have drawn over ground you know to be a single
material, names each signature and its material class, and optionally adds a photometric
shade endmember. Import Library… reads an external spectral library and
convolves each spectrum onto this sensor's own bands through a Gaussian response built
from each band's stated width. A band that states no width falls back to
interpolation, and the set records which was used band by band. Whether the grid came from the sensor's
published centres or from the wavelengths this particular file happens to carry is
written into the set's provenance, because those are different claims. Sets can be
deleted from the sheet that made them.
The two halves have to agree about radiometry.
Pixels are states whether this raster holds reflectance or raw counts. A
library of reflectance spectra unmixed against digital numbers produces fractions with
no physical meaning. Bands that cannot state a wavelength are left out of
a derived set, and the sheet says how many.
In these two sheets the selected polygons mean the ground
the signatures came from, and the result covers the whole image.
Spectral Unmixing
Processing ▸ Analysis ▸ Spectral Unmixing…
Solves each pixel as a mixture of the set's materials and writes the fractions. That
is how a 10 m or 500 m pixel says how much bare soil, green vegetation or snow
it holds. There are three models. The choice between them is about endmember
variability: one signature per material rarely holds over a whole scene.
Single model puts every signature in one matrix. It is right when the
set was derived from this scene, because then the compromise was made deliberately over
ground you chose. MESMA solves every pixel against every candidate model
and keeps the winner: fewest materials first, then lowest residual.
Materials per model bounds the complexity, and Largest
residual bounds admissibility. AutoMCU solves each pixel many
times, drawing a different signature from each material's bundle. It reports the mean
and the standard deviation, and a fraction arrives with an error bar. Fractions
sum to one is the constraint that makes a shade endmember identifiable.
Single and MESMA write one fraction band per
material, then RMSE, then the winning model. AutoMCU writes a mean and a standard
deviation per material, then RMSE, then the share of draws that were admissible.
Because “none of this pixel” is itself a measurement, materials a
winning model left out are written as zero. Nodata would claim
the model had no opinion.
Without a residual bound, the simplest admissible
model wins however badly it fits, and a pixel of three materials is reported as two.
The bound is what makes model selection mean anything. AutoMCU needs a set with
alternatives in a bundle. Without them every draw is the same draw, and the spread is
zero everywhere. The sheet says so before you run it. A Monte Carlo product whose seed
is not recorded cannot be reproduced by anyone, including you. AutoMCU writes its seed
into the output.
Spectral Angle Mapper
Processing ▸ Analysis ▸ Spectral Angle Mapper…
Labels each pixel with the reference spectrum it points most nearly at. It measures the
angle between the pixel's spectrum and each reference and ignores their lengths.
Illumination, slope and shade do not move the answer the way a distance measure would.
The angle is written beside the class, and a confident match and a distant one are
distinguishable.
Only match within an angle leaves a pixel unclassified beyond the
largest angle you set. The angle is still written, and “nothing was within 5 degrees
and the nearest was 23” stays readable. Unbounded matching is right only where the
set is known to span the scene. Remove the continuum first divides both
pixel and references by their own convex hull and compares absorption-feature shape.
That is usually better for minerals and worse for vegetation and land cover. It is a
different measurement and is recorded as one. Write every reference's
angle adds one band per reference. It is the only way to see that a pixel
was nearly a tie.
Change Detection
Processing ▸ Analysis ▸ Change Detection…
Compares two dates and reports both the classes and the continuous surface behind them:
differencing, log-ratio for radar, index difference including dNBR burn severity, or
IR-MAD's no-change probability as the threshold.
Change detection between scenes that were not
radiometrically normalised measures the atmosphere as much as the ground. That
assumption travels with the product into every figure computed from it, and the panel
requires you to state what was done.
Because every method compares co-located pixels, the
two dates have to be on the same grid: same size, CRS and pixel size. Resample to Match
Layer, or Co-register, first.
DEM of Difference
Processing ▸ Analysis ▸ DEM of Difference…
Differences two epochs of terrain and reports the volume of soil lost and gained, with
the uncertainty that makes the figure defensible: a level of detection measured from
ground you mark as stable, a probability of real change per cell, and a
spatial-coherence pass that keeps a coherent patch of marginal cells and drops isolated
spikes.
A rigid correction removes a constant vertical
offset, and real uniform soil loss is a constant vertical offset. On epochs tied to
shared ground control, the correction deletes exactly the change being measured and
reports near zero. For that reason the co-registration here only checks
the alignment, and stays off.
A susceptibility model says where erosion can
happen. This says where it did, over one interval. Two dry years read as no erosion, and
a single storm between flights reads as catastrophic. The product carries both dates,
and it is per year only if somebody asked for it to be.
InSAR Displacement
Processing ▸ Analysis ▸ InSAR Displacement…
Turns a geocoded unwrapped interferogram into displacement, in metres, with the
coherence that says which of it is a measurement. It has millimetre precision at
30–80 m posting and resolves slow motion: creep, subsidence, a slope moving before it
fails.
It is blind exactly where the surface was
disturbed. Erosion rearranges the scatterers the phase is measured from. Coherence falls
to zero and the cell is withheld, and that hole is the evidence. It also measures range
change along one line of sight. Projecting that onto the vertical
assumes the ground moved straight up or down.
It complements a DEM of Difference. Used together,
this says where to look and the DoD says what it cost.
Slope
Processing ▸ Analysis ▸ Slope…
Writes the steepness of an elevation model as a raster, in degrees, percent or rise over
run, optionally with the downslope bearing beside it. It uses Horn's 3 × 3 kernel, the
same one the relief shading and the topographic correction use. A slope class and a
hillshade cannot disagree about the same cell. Flat ground gets no aspect.
A slope is a height over a ground distance, and
most DEMs state only the second. Where nothing declares a vertical unit, the heights are
taken as metres and the panel says so. A DEM in feet read as metres comes out 3.28 times
too steep. Rolling country is reported as steep, and it fails in no visible
way.
Reclassify
Processing ▸ Analysis ▸ Reclassify…
Turns one band of continuous measurements into named classes by a table of breaks,
writing a class raster with an attribute table. Where the breaks fall is the whole of
what the output says, and a threshold typed with nothing behind it is chosen blind.
The band's own distribution is drawn behind the breaks.
A value outside every class is left
unclassified. Clamping would let a top break typed as 3.6 instead of 36
report a whole property as the steepest class, complete and confident, with no gap
anywhere to notice. Each class runs up to but not including the next. A value on a
break belongs to exactly one.
Land Resource Inventory
Processing ▸ Analysis ▸ Land Resource Inventory…
The New Zealand Land Use Capability system. Intersects up to five factor layers (rock
type, soil, slope, erosion, vegetation) into inventory units, sieves them to a minimum
mappable area, and looks each combination up in an editable rule table. The output is a
unit map with a full attribute table: every unit's factor codes, its area, its LUC class
1 to 8 with its e/w/s/c subclass, and where each of its five statements came from.
Because good drainage cannot compensate for a 30
degree slope, the class comes from the most limiting factor. Soil,
slope and vegetation are required. Without one, the units are mapped and left
unclassified. Filling the gap would classify them optimistically. A severity of 0
records that somebody looked and found nothing. It is kept quite separate from nobody
having looked.
It is labelled a draft because the rule table
automates only the bookkeeping and the judgement stays yours. Error compounds across an
intersection, and no unit is more reliable than its worst factor. The provenance is
therefore on every row.
Terrain products
The complete-window rule, and a radius in metres
Every windowed terrain product
The four jobs below are offered where Slope is, on a layer recognised as an elevation
model. They share two rules. A radius is typed in metres and converted on this model's
own cell size (10 m is 10 cells at 1 m and 20 at 0.5 m). The file records both.
The window also has to be complete. A cell whose radius runs off the raster or into
nodata is withheld. Every product carries a ring of one radius round the border and
round every hole. Filling the ring would measure against surroundings that are partly
imagined, and these are measurements. RVT mirrors its model outward at the edge. Here
the margin is withheld, and the help says so.
The relief shading, for the interactive picture; the
Terrain Composite, for the archaeological stacks built from these products.
Relative Elevation
Processing ▸ Analysis ▸ Relative Elevation…
Writes a cell's height against its surroundings: the local relief model (the height
minus the mean within a radius, Hesse 2010, the same number as a topographic position
index at a filled window), the deviation from mean elevation (that difference over the
window's standard deviation), the multi-scale topographic position (the deviation of
largest magnitude across three scale ranges, as three bands) and the multi-scale
relief model (Orengo and Petrie 2018). Archaeologists run these on airborne LiDAR to
see banks, ditches and mounds under the general lie of the land. At the same radius in
millimetres, they find a petroglyph in a photogrammetry model of a rock panel.
RVT's MSTP picture is
1 − exp(−1.2·|DEV|) per scale as red, green and blue. No
stretch of the written deviation can make it, because the fold at zero is no stretch. A
toggle on the sheet writes that picture in place of the deviation, on 0…1 with the
formula recorded. The e4MSTP recipe uses it.
Terrain Form
Processing ▸ Analysis ▸ Terrain Form…
Writes the second derivatives of an elevation model on the same 3 × 3 grid as Slope:
profile curvature along the slope, plan curvature across it and the Laplacian, all in
1/m (Zevenbergen and Thorne 1987), or Riley's terrain ruggedness index, the root of the
summed squared height differences to the eight neighbours, in metres. Curvature is
how a bank, a ditch and a lynchet differ from the hillside they sit on. Ruggedness is
the local roughness a ploughed-out barrow and a stone setting both raise.
The sign is Zevenbergen and Thorne's own. A bowl
is negative in profile and a dome positive, the opposite of what some GIS packages
print. Profile and plan are withheld on flat ground, where there is no slope
direction to take them along. The Laplacian is not withheld. Heights in feet on a metre grid need
the vertical unit stated, as Slope does.
Terrain Visibility
Processing ▸ Analysis ▸ Terrain Visibility…
Writes what a cell can see of the sky and what it looks down on, from the ray march
the relief shading already runs: positive openness (90° minus the mean horizon angle
within a radius, the horizon allowed below level so a summit exceeds 90°) and negative
openness (the same on the inverted model, so a pit does); Zakšek's sky-view factor
and its anisotropic form (the sky a cell sees, 0 to 1, optionally weighted towards a
main direction); Hesse's local dominance (the mean angle at which an observer 1.7 m
up looks down on the ground between two radii); the openness difference (positive
minus negative, marched both ways and written as one signed product, convex ground
above zero and hollows below); Kennelly and Stewart's sky illumination (the cell's
own tilted surface lit by a uniform or a CIE overcast sky, each direction's sky above
its horizon weighted by how squarely the surface faces it, 1 on open flat ground); and
the sunlit mask, 1 where the sun clears the horizon in its direction. Openness and the
sky-view factor are the layers the Visualization for Archaeological Topography is
built from. The difference is the relief layer of the colour relief image map.
Two sky-view factors exist in this app, and both
are named in their products. The relief shading's is a mean of cos² of the horizon.
This one is 1 minus the mean sine, which the published 0.7–1.0 display cut assumes.
The whole model goes to the GPU at once. A decimated measurement would be a different
measurement, and a model the memory budget refuses is refused outright. A ray that
leaves the raster or meets nodata before the radius withholds its cell. The sky
products march 100 cells by default, and on a small tile most of it is withheld. They
are for sheets.
Multi-directional Hillshade
Processing ▸ Analysis ▸ Multi-directional Hillshade…
Writes a hillshade from every direction at once, one band per azimuth evenly spaced
from north (Hobbs 1999). It uses the same Horn gradient as Slope and the relief shading,
clamped at zero because a hillshade is light received. A single beam hides whatever
lies parallel to it and drowns whatever faces it. Sixteen miss nothing. The first
three principal components of the stack (Devereux, Amable and Crow 2008) carry almost
all of it in one picture, and the panel can fit and write them beside the stack.
The relief shading blends its lights into one
grey and stays display-only. This job writes every light as its own band. A composite
of three of them, or the components, can then be measured and compared. Sixteen Float32 bands
are sixteen times the model's size on disk.
Terrain Composite (VAT)
Processing ▸ Analysis ▸ Terrain Composite (VAT)…
Assembles an archaeological composite as a stack of ordinary layers from the products
above, running the jobs it needs through the Jobs panel and grouping the results under
the recipe's name. Eight recipes, transcribed from RVT's own sources. VAT
(general terrain): a hillshade from 315° at the bottom, the slope in
luminosity over it on an inverted grey ramp so steep ground is dark, positive openness
in overlay and the sky-view factor multiplied on top, each cut at the published range.
VAT (flat terrain) lowers the sun to 15°, narrows every cut, widens the
radius to 20 cells and skips the nearest 40 % of it so noise does not read as relief.
VAT (combined) lays the general stack, as one picture, at half over
the flat one. Colour relief image map puts slope on an orange–red ramp
with the openness difference laid over it in luminosity and then overlay. Convex
ground lightens and hollows darken. Prismatic openness lays positive
and negative openness at half each over the slope, with no light direction.
e4MSTP overlays RVT's MSTP picture on slope in red, with two composited
pictures multiplied between them. The last two are pictures of the multi-directional hillshade:
three directions as red, green and blue, and the PCA
of sixteen as RGB, each component cut between its 2nd and 98th percentiles when it is
made.
The composite is a picture. Changing any row's blend
mode, opacity or stretch in the Layers panel changes the picture. Nothing blended here
can leave as a raster. An export takes the products. Because openness and the sky-view
factor put the whole model on the GPU, the run is several jobs in the Jobs panel, one
after another. MSTP's broad scale is 500 cells. Like every windowed product, e4MSTP
withholds a 500-cell margin.
The recipes were rendered on two LINZ 1 m tiles before
anyone saw them in the app. That rendering found the inverted slope ramp and a
double-drawn translucent layer. Both are fixed and pinned by tests written from what
was seen. Each group remembers which recipe made it. A group carrying a levels cut says
so in its subtitle.
Classification
Classify · unsupervised
Processing ▸ Classification ▸ Classify…
Finds groupings in the data without any training: K-Means with k-means++/maximin
seeding, ISODATA with adaptive split and merge, or a Gaussian/Mahalanobis mixture. All
deterministic and multicore, with an optional Metal backend for the assignment step.
Images too large for memory are fitted on a decimated sample and assigned block by
block. The output is a class raster with editable per-class colours and per-class ground
areas in the Classes inspector.
The result is a class raster whose numbers mean
nothing until you interpret them. The preview fits on the visible extent. It fits the
classes that happen to be in view. Use it to choose k by looking, and let the full run
fit the scene.
Training classes
Inspector ▸ Classification ▸ Training classes · ⌘3
A class is a name, a colour and a set of drawn polygons. Draw over ground you know,
select the polygons and press Assign, or right-click a polygon to file
it directly. Each row carries its polygon count and its pixel count.
The pixel count is the figure that matters. A class needs more pixels than bands to fit
a covariance at all, and ten to a hundred times that for the estimate to be stable. The
row turns amber when it is thin for the bands you have selected. The advice names both
remedies: draw more, or select fewer bands.
Classes can be merged, and the class list undoes.
Select Its Polygons puts a class's ground back under the cursor. That
is how you find the one that is dragging a pair together.
Which bands train, and the quality mask
Inspector ▸ Classification ▸ Bands · Quality mask
Every band is used unless you say otherwise. Untick the ones that carry no information
for these classes. A thin class over sixty bands is ample over six, and band selection
is often the cheaper of the two fixes. Once a separability check has run, Rank
orders the bands by how well each one separates the weakest pair, scored one band at a
time. Because bands are correlated, those scores do not add up to the matrix. Read them
as a ranking.
A run that honoured no mask is a fact about the result. The Quality mask
section states whether one was found beside the layer, whether or not there is one. With
Reject masked training pixels on, cloud, shadow and fill are dropped from
the training pixels only. The map still covers them. Masking the output is a separate
decision, and it changes every area figure.
A polygon drawn over forest that clipped the
edge of a cloud teaches the classifier that cloud is forest, and the map that comes out is
plausible everywhere. That failure has no symptom. Landsat and Sentinel-2 downloads carry
a quality raster. A composite may not.
Separability
Inspector ▸ Classification ▸ Separability
Scores every pair of classes before anything is fitted, as Jeffries-Matusita or
transformed divergence, and reports each pair as separable, marginal or not distinct. Two
classes that overlap in feature space cannot be told apart by any classifier, however
good. This check says whether the problem is the method or the classes. The matrix
exports as CSV, one row per pair, and the list filters to the problem pairs.
Changing the band selection or the mask setting invalidates
the report. Otherwise a matrix computed over different pixels would stay on screen.
The class signature chart beside it draws each class's mean with one standard deviation.
Envelopes lying on top of each other are the same finding in a different form.
Supervised Classification
Processing ▸ Classification ▸ Supervised Classification…
Assigns a class to every pixel from the training polygons you have labelled.
Random Forest is the workhorse. It is an ensemble of trees, each on a
bootstrap sample with a random subset of bands per split. It makes no assumption about the
shape of a class and tolerates correlated bands and some mislabelled pixels. Maximum
Likelihood fits a full covariance ellipsoid per class and is still the best where
classes really are roughly Gaussian and there are pixels enough to estimate one.
Minimum Distance needs very few training pixels. Spectral
Angle Mapper ignores brightness. The forest exposes trees, maximum depth and a
fixed seed. The same training set gives the same map every run. Change the seed only to
see how much the answer depends on the bootstrap.
Blocked cross-validation, under Validation, refits the classifier with
whole blocks of ground held out. A held-out pixel's neighbours were then not trained on. A
random split over training polygons reports an accuracy inflated by up to 28 % by spatial
autocorrelation. The blocked figure corrects it. Derive the block size from
the data fits a variogram per band over the training pixels and takes the median
range. It reports the size it used as a ground distance, and refuses where the pixels are
too few or too clustered to fit one. Treat the derived figure as a floor. A block edge set
by hand must be larger than your polygons. Otherwise a polygon straddling a boundary puts
near-duplicate pixels on both sides, and the optimism returns.
Out-of-bag accuracy and the blocked figure both
describe the classifier. An accuracy assessment describes the
map and needs an independent reference sample. Neither figure is an accuracy
assessment. The panel reports the pair together with Optimism, the
difference between them. Neither number states that quantity alone. Because validation
refits once per fold, multiplying fitting time by the fold count, it is off by
default.
A fold that cannot be scored says why. Usually a held-out
block took a whole class with it. A refusal to block is a statement about the training
set, and it never costs you the map.
Accuracy assessment
Inspector ▸ Classification ▸ Accuracy
The assessment of the map itself, on an independent sample. Choose how many sample units
and how they are allocated (proportional to area, equal per class, or a floor on rare
classes with the rest spread by area) and generate the sample. The points are drawn by
reservoir sampling in one pass. This costs the same on a 500-megapixel map as on a
small one. Then label each point from what you know of the ground, stepping through them,
and read the assessment: overall accuracy, quantity disagreement, allocation disagreement
and kappa, with the confusion matrix and a summary that both export.
Equal-per-class allocation is what makes a rare class's
own accuracy readable. Proportional allocation is what makes the overall figure an
estimate of the map. Quantity and allocation disagreement separate “the areas are
wrong” from “the areas are right and in the wrong places”. One
accuracy figure cannot.
Proximal survey
Importing a proximal soil survey
File ▸ Import Proximal Survey…
Reads a towed electromagnetic-induction logger file and produces three georeferenced
products in one window: a point raster of what was measured, an interpolated surface per
channel, and optionally an inverted conductivity-against-depth stack. The panel lays the
pipeline out as a stack of stages. Every filter is a row that switches off, and the
pipeline re-runs on any change. Excluded records stay visible in grey, and you can see
where a filter bites. Stages run in order: parse and project, acquisition geometry, motion
filter, range filter, ferrous interference, along-track despike, rolling mean, GNSS
latency, sensor offset, instrument drift, temperature standardisation, and calibration
against reference profiles.
An unrecognised instrument gets no operating
frequency and no height. A plausible figure substituted there would carry into every
product. The stages that need them say so.
Plan Soil Pits
Processing ▸ Proximal survey ▸ Plan Soil Pits…
Takes a logger export and produces a ranked soil-pit plan. In one act it grids the
survey, inverts it, groups the ground into management zones and sites the pits.
Calibration wants ordinary ground, training wants unbiased coverage, and a diagnostic
pit wants the anomalies. The three purposes are kept apart, and a site never carries two.
Because budgets shrink in the field, the plan is a
ranked list. Cutting it from the bottom leaves a usable set of each role. The panel
says what stopping at any depth would leave. Below five calibration references the
survey will not calibrate at all.
The zones survive calibration exactly. The pits can be
sited today and the laboratory results can arrive weeks later.
Substrate Units
Processing ▸ Proximal survey ▸ Substrate Units…
Groups the inverted survey into substrate units and draws them as polygons. Two places
can have identical shallow readings and completely different profiles, and it is the
profile that decides rooting depth and drainage. For that reason it clusters the whole
column: log conductivity per layer, plus where the profile steps and
by how much.
Because nothing in a clustering knows about space,
clustering the raster and polygonising afterwards produces isolated pixels and
incoherent units. This job segments first, then clusters the segments. The supercell
count and the compactness are your conceptual model of the landscape. They therefore have a
live preview.
Unlike the field pass's management zones, these come
from the inversion. Their boundaries move when the laboratory results land. Re-run
once the survey is calibrated.
Sounding Posterior
Processing ▸ Proximal survey ▸ Sounding Posterior…
Samples the posterior distribution of the layered model under one sounding. The width
of each layer's interval says how well these coils constrain it. Click a cell on the map
to choose the sounding and set how many layers to ask the readings to support. Past a
factor of ten, the data do not resolve that layer at all, however confident a
single-model inversion looks.
Because a survey-wide sampler is tens of thousands
of correlated parameters and mixes in no useful time, this works one sounding at a
time. Invert the survey first, then sample the few soundings a decision rests on.
Rank Substrate Units
Processing ▸ Proximal survey ▸ Rank Substrate Units…
Turns substrate units into a Land Resource Inventory factor layer. Each unit is listed
with the evidence it was built from (the depth of its strongest conductivity step, its
layer conductivities, its area and how confidently it was assigned) and you give each one
a class from the handbook's own coding.
The same contrast depth is a severe limitation on
one property and a moderate one on the next. That is a judgement about the country, and
nothing here proposes a severity. A unit left unranked comes out unclassified.
Viewing an inverted survey as a volume
Right-click the layer ▸ View in 3D… · Inspector ▸ Volume
A ray-marched view of a layered conductivity model, with an orbit camera, a colour map
and an opacity curve for picking out a range of values, optional depth-slice shading, the
survey track, and depth posts scaled to the survey's own coils. Two guillotine blades are
objects in the view. Drag an end post to cut, or click inside the volume to bring both
blades to that point. Reset parks them at the edge. A section beneath stays linked to
what the blades expose.
Because the half-space below the deepest
boundary is an assumption of homogeneity, it is left out. Where the file carries a depth
of investigation, the volume is clipped at it. Where it does not, the whole model depth
is drawn, including ground the readings never reached, and the panel says so. A model
too large for a single 3D texture is drawn decimated and states the factor. The readout
and the section still read the file.
It is offered only where the file's own bands declare the
model's layers. It cannot be pointed at a stack that merely looks like one. Vertical
exaggeration and shading are display scales. No sample moves and no value changes.
Downloading data
Searching public archives
File ▸ Import from Earth Search… (⇧⌘I)
Searches by area, date window and cloud cover, then downloads the chosen bands as a
tracked job. Five sources: Earth Search on AWS, Microsoft Planetary Computer, CNES
GEODES (the SPOT World Heritage archive), the Alaska Satellite Facility (Sentinel-1
and NISAR products, including the unwrapped interferograms InSAR Displacement reads)
and LINZ. Landsat is free on Planetary Computer and requester-pays on Earth Search.
GEODES needs a free API key for downloads and none for searching. MODIS is on
Planetary Computer only, grouped under Reflectance, Vegetation, Temperature and fire,
and Snow and ice. It arrives on the sinusoidal grid. Reproject is usually needed
before combining it with a UTM or NZTM scene, to a local projected CRS where the tile
straddles 180°.
The area is picked on a built-in world map or seeded from
the current raster's extent. Where an archive publishes a browse image, it is drawn on
the map inside the scene's own footprint. It is trimmed to its opaque content, and a
transparent margin does not shift it. Bands on different native grids are assembled as
separate stacks and never resampled together. A file already on disk is not fetched
again. A finished download opens through the same door as a file from the Finder, and a
delivery is recognised as one. Recognition looks at the scene's own folder and at most
one level below the folder it is handed. The downloads folder above a scene is not
offered as a delivery.
New Zealand imagery and elevation from LINZ
Import panel ▸ Source ▸ LINZ (Aotearoa / New Zealand)
Because LINZ publishes a static catalogue with no search service behind it, this source
is selected by map sheet. The world map becomes the Topo50 1:50,000 sheet grid. Click the
sheets you want, or drag a band across the grid to take every sheet it touches.
Find Surveys then asks the bucket which aerial surveys hold tiles for them.
The results are surveys, newest first. Over one sheet, that list is a time series of
the same ground across decades. Choosing a survey draws its tiles. Click or drag on the
map or the list, which are one selection. Hovering names the sheet the way LINZ
printed it, and the tile by its filename.
Everything is anonymous and licensed CC BY 4.0.
Attribution to LINZ is required. Drafts are hidden by default, because LINZ can replace
them. A dragged band adds to what is already selected and never resets a listed survey's
tiles.
A download failed part-way
The Downloads list at the bottom of the import panel
A stalled or dropped transfer is retried a few times on its own and resumed where the
archive allows it. If it still fails, the row states what went wrong in one sentence. It
offers Retry where trying again can help, as after a timeout or a lost
connection. A refusal such as HTTP 403 would answer the same way twice, and it is not
offered one.
Files that finished are kept, and Retry fetches only what
is still missing. A partial raster that opens looks complete until something reads its
far end. The file that was mid-transfer is discarded. Cancelling keeps the finished
files too. The retry appears as a new row, and the failure stays on
record.
Files & saving
Exporting
Share glyph in the toolbar · File ▸ Export (⌘E)
Writes a GeoTIFF of source measurements through GDAL, carrying any crop through as a
source window and persisting attribute-table edits. The rendered picture exports
separately as PNG, HEIC or OpenEXR through Image I/O. Every GeoTIFF the app writes is
ZSTD-compressed and tiled. A file written without its georeference would look complete,
and a writer that cannot copy the georeference throws.
Because the GeoTIFF is measurements, annotations are
not burned into it. They do burn into the rendered picture. Rendered exports are SDR unless
HDR is picked explicitly.
Saving the window as a project
File ▸ Save Project… (⌘S) · File ▸ Open Project… (⇧⌘O)
A .hachureproj file records the arrangement: every project in
the window and its coordinate system, the layer tree with its groups, blend modes and
any levels a preset put on a group, display settings including a reversed ramp, the
light and mode of a relit raster, polygons, annotations, training classes and the plans
a survey produced. The images themselves are referenced. Keep them where they are.
Opening a project rebuilds the window. Anything that has moved since is reported by
name. Saving offers to copy any layer still living in the temporary folder into a
folder beside the project.
A project that references a layer still living in a
temporary file will not reopen intact. Saving says so at the one moment it can be
acted on. Save those layers somewhere first.
Saving derived layers when a window closes
Automatic when closing a window, and on Quit
A processing job writes its result into a temporary file and opens it as a layer. That
makes the Processing menu feel immediate. It also means closing the window would throw
the result away. Closing a window holding such layers lists them first, with
a tick and a format for each, and Save, Don't Save or Cancel. The formats are all
scientific containers: GeoTIFF, Cloud-Optimised GeoTIFF, KEA and ERDAS Imagine.
One layer gets a save panel, several get a folder chooser,
and two layers sharing a name are numbered. A layer already saved somewhere you chose is
not offered again.
Apple Photos
File ▸ Export ▸ Add to Photos · File ▸ Import from Photos
Add to Photos renders what is on screen and files it in a Hachure album, created the
first time. It is the same picture the rendered export writes, display bands through
their tone curves. The file says the curve is baked into its pixels, and the scene's
centre goes in as GPS. A photo library has nowhere to put a float HDR image, and a
GeoTIFF of measurements does not belong in one. Only PNG and HEIC are offered.
Because an imported photograph carries no coordinate
system, the coordinate readout, the scale bar and the geometry commands stay unavailable
for it. The pixel readout, band maths, the decorrelation stretch and the drawing tools
work as usual.
Settings
The Workspace, and why a folder is sometimes asked for
Settings ▸ General ▸ Workspace
macOS gives an app exactly the files chosen in an open panel and nothing beside them.
Several formats are not one file: a shapefile keeps its projection in a sibling
.prj and its attributes in a .dbf,
and a satellite delivery is a manifest beside its band files. There is no way to widen
the permission without you choosing the wider thing. When a companion cannot be read,
Hachure asks for the enclosing folder.
Naming a Workspace folder answers that once. Everything
inside it opens without a prompt, and the grant is remembered across launches. Nothing
outside it is affected, and Clear gives the access back. The Workspace is also the first
folder the Organiser lists.
Processing memory budget
Settings ▸ General ▸ Processing Memory
A 10–80 % ceiling on unified memory, 50 % by default, that every whole-image job checks
before reading a pixel. An over-large job fails in a second with the required and
available figures on screen. Run Anyway is offered, with Cancel as the default. Under
memory pressure from elsewhere on the Mac, every window releases the caches it can
rebuild. GDAL's block cache is held down until the pressure clears. Nothing on screen
changes.
The Organiser's cache
Settings ▸ General ▸ Organiser
The Organiser keeps each scene's description and thumbnail between launches, under a
byte cap you set. A folder of two hundred deliveries lists at once on the second
opening. Clear empties it, and the next opening reads everything again.
The sensor catalogue
Settings ▸ Satellites
Twenty sensors with per-band name, aliases, common name, centre wavelength, FWHM,
native ground sample distance, spectral role, polarisation and thermal constants, plus
versioned calibration profiles keyed on processing level, collection, baseline and
acquisition date. It is user-editable: sensors can be added or overridden, and edits are
validated before they are saved. The centres are the agencies' measured ones. ASTER's,
for instance, are derived from JPL's published spectral response functions, and a test
holds them to the nanometre.
The catalogue is what lets an index written once resolve
across sensors that number their bands differently.
If something is wrong
Two rasters will not overlay
Processing ▸ Geometry ▸ Reproject…
An added raster must share the base's CRS. Reproject one onto the other's CRS, then add
it again. If they share a CRS but sit slightly apart, that is a registration problem.
Try Co-registration first.
A job refuses with “needs the same grid”
Processing ▸ Geometry ▸ Resample to Match Layer…
Regression and IR-MAD normalisation, every change-detection method, and DEM of Difference
all compare co-located pixels. The two rasters must have the same size, CRS and pixel
size. Resample to Match Layer puts one on the other's exact grid. Use nearest for
anything thematic.
The image looks flat, dark or washed out
Inspector ▸ Bands ▸ Stretch
Raw 12- and 16-bit radiometric data is near-flat without a stretch, and Hachure applies
none on open. Percentile clip with a modest gamma is the usual first move. The stretch
is display exposure only and changes nothing stored.
An index came out smooth and plausible and wrong
Inspector ▸ Bands ▸ Composite
Check the spectral roles. A named index resolves against the bands the stack says are
NIR and Red. If those are wrong, the arithmetic still succeeds and produces a convincing
surface of the wrong two bands. Correct the role on the band's row, then re-run.
A terrain product has a blank ring round the edge
Processing ▸ Analysis ▸ the terrain products
That is the complete-window rule. A cell whose radius runs off the raster or into
nodata is withheld. Every windowed product carries a ring of one radius round the
border and round every hole. The sky products march 100 cells by default and
withhold most of a small tile. Run them on a sheet, or accept the ring. The alternative
would be to measure against surroundings the model does not have.
A relit image is white, or black
Inspector ▸ Bands ▸ Relight
White across the whole panel means the coefficients are on a different scale from the
one the shader expects. A raster fitted by this app records its sample scale, and a PTM
carries its own. White therefore points at a file made elsewhere. Black under diffuse
gain comes from the mathematics. A gain of three under a 20° light reaches zero well
before the horizon.
Raise the light or lower the gain.
A shapefile opens without its projection
Settings ▸ General ▸ Workspace
The .prj and .dbf are separate files
and the sandbox grants only what you selected. Name a Workspace folder that contains
them, or answer the folder prompt when it appears.
A file will not open at all
File ▸ Open
Hachure reads what its curated GDAL driver set reads. HEIC, HEIF and AVIF are left out
of it on licence grounds. They are converted through the system's own image framework
before anything else looks at the file, whether they arrive through File ▸ Import
from Photos, from the Finder, at launch, or inside a folder. The converted copy
is written into Hachure's own Application Support folder. Nothing is written beside your
data. An alert says that it happened, why, and where the copy went.
A file that still will not open is one no bundled
driver reads. Converting it with gdal_translate outside the app
is the usual route.