Imager

The Imager turns grids into a colour image. Open a grid - an elevation model, a magnetic or gravity grid, any band of measurements - decide how its values become colours, and save the result as a georeferenced image that any GIS or viewer can show. How the values become colours is an algorithm: a small diagram of steps that you can use as supplied, change, or build yourself, for anything from a simple pseudocolour image to a ratio of two grids. Changes appear as you make them, and the saved image is exactly what you see.

Usually you will make an image once, save it, close the Imager and use the image from disk from then on.

Opening the Dialog

Hover over the Data Processing icon in the right tool panel and click Imaging..., or drop a grid file onto that button. Each click or drop opens another Imager, so several can be open at once to compare grids or algorithms side by side. Once the Imager is open, the Open a grid button at the left of its toolbar opens a grid into it.

The window has a toolbar across the top and shows the image below it. Make the window as large as you like: the image fills it. The Imager starts with the Pseudocolour algorithm, which colours one band of one grid through a colour ramp.

Viewing the Image

The image is shown fitted to the window to begin with. When a grid is too large to show every cell, it is drawn from its overviews (reduced-resolution copies), so even a very large grid appears at once.

• Mouse wheel zooms in and out about the pointer. Zoom in and the full resolution is read for the part you are looking at; keep zooming and the individual cells appear.
• Drag with the left button to pan.
• Zoom in, Zoom out and Zoom fit on the toolbar do the same about the centre of the window.

The line under the image follows the pointer with its location and the value of each grid beneath it. Where there is no value the image is transparent. If something is wrong with the algorithm, the line says what in red, and the image stays as it last was.

Algorithms

Click Edit the algorithm on the toolbar to open the algorithm window. It holds the diagram: boxes called nodes, joined by links that carry data from the pins on the right of one node to the pins on the left of the next. Click a node to open its settings in a window of its own. Open as many as you like, move them wherever suits you, and keep them open while the algorithm window is closed. They come back where you left them when the Imager or the algorithm is opened again, until the project closes.

Blue pins carry values and orange pins carry colours. A link can only join two pins of the same colour, each input takes one link, and an output can feed as many inputs as you like.

An image always has exactly one Image node and at least one Grid input.

Editing the Diagram

• Right click the background to add a node.
• Drag from one pin to another to link them. A link that is not allowed turns red and says why.
• Drag from an output onto the background to add a node already linked to it. The menu lists only the nodes with an input that can take that output.
• Click a node to select it and open its settings window, or bring that window to the front if it is already open. Drag it to move it.
• Press Delete to remove the selected nodes and links, or right click a node and choose Delete.
• Mouse wheel zooms the diagram, right drag pans it, and F fits it to the window.

A node with a warning sign has a problem; hover over it, or open its settings, to read what it is. The image keeps showing the last algorithm that worked until the problem is fixed.

Grid Inputs

Click a Grid input and click the browse button in its settings to choose its file, or drop a grid file from your file manager onto the node. The Open a grid button on the Imager's toolbar does the same for the first Grid input that has no file yet.

Several grids can be combined. They must share a coordinate system and be north up, but they need not cover the same area or have the same cell size: each is sampled where it lies. Outside a grid there is no value.

The settings of a Grid input show the coordinate system of its grid. If the file declares none, or the wrong one, click the CRS button beside it to choose the right one. The choice is saved with the algorithm, and (override) is shown after its name. Click Use the file's CRS to go back to the one in the file. Choosing a different file for the Grid input also removes the override. The chosen coordinate system is used to check the grids belong together and is written to exported images.

Colour LUT and LUT

These use the same editor as continuous colour on every layer: a transform that says which input values map to which part of the colour ramp, and for a Colour LUT the ramp itself, chosen from the list beneath the colour bar.

The transform starts as a straight line from the lowest value reaching the node to the highest, so the whole ramp is used. For a band straight from a grid the range comes from the file; for anything else - the result of an equation, say - the Imager works the values out over the whole area first, which takes a moment. Drag the end points to clip the range, or add points along the line to stretch some part of the range and compress another. The buttons above the plot reset the transform to the data range or to a straight line.

Behind the transform are two histograms. The grey line rising from the bottom is how the input values are spread. The line running in from the left edge is how the output is spread once the transform has been applied: for a Colour LUT it is drawn in the colours of the ramp, for a LUT it is white. It follows the transform as you drag its points, so you can see how much of the ramp each part of the data takes up.

Autotune sets the transform from the data for you. It clips the extreme values at each end so that a few outliers saturate rather than squash everything else, then bends the line towards a histogram equalisation only as far as the data needs: a bell-shaped spread of values stays close to linear, while a skewed or long-tailed one is bent more. A single value that dominates the grid, such as padding, is treated as one colour and does not take up the ramp. The Autotune button is beside Equalise above the plot, and the Autotune button on the Imager's toolbar tunes every LUT in the algorithm at once, Colour LUTs and LUTs alike. A LUT keeps its output range and spreads whatever feeds it over that range, so a LUT between a Sun shade and the Image spreads the shade over the LUT's range.

A LUT node produces values rather than colours. Set its Output range and shape the transform between them, for example to rescale a grid to 0 to 1 before an equation.

Ternary Images

A ternary image shows three grids at once, one in each of red, green and blue, so that what each one has to say and where they agree can be read from the colour. Airborne radiometrics are the usual example: potassium in red, thorium in green and uranium in blue.

A Colour LUT has a Red, a Green and a Blue output beside its Colour output. These give a value rather than a colour: how strongly that one channel burns, from nothing to full. Link one of them to the matching input of the Image node and the node becomes a channel of the image. Only one output of a Colour LUT can be used at a time, since a node is either a whole colour or one channel of one. While a channel output is linked the ramp is that colour and cannot be changed or reversed; the transform is edited exactly as usual, and it alone decides how the values are spread across the channel.

The Image node takes Red, Green, Blue and Alpha as well as Colour. Each replaces that channel of the colour, so all three together make an image with no Colour linked at all, and one on its own replaces a single channel of a colour that is linked. Alpha decides what is see-through: a channel with no value there is empty, and where no linked channel has a value the image is transparent.

The Image node also takes Hue, Saturation and Intensity, each a value from 0 to 1. Hue runs round the colour wheel from red at 0, through green and blue, and back to red at 1. Saturation goes from grey to the pure colour, and Intensity from black to full brightness. These replace their part of whatever colour the other inputs make, after Red, Green and Blue. With nothing else linked, Intensity is full, and Saturation is full when Hue is linked. A classic use is one grid through a LUT into Hue and a second grid into Intensity, so the first is read from the colour and the second from the brightness. Where Hue has no value the pixel is grey, and where Saturation or Intensity has none it takes 0; where none of them has a value the image is transparent.

The Ternary preset is set up this way, with three Grid inputs, three Colour LUTs and the three channels of the image. Open a grid into each; three bands of the one file work just as well as three files, as radiometrics usually are.

Equations

An Equation node has inputs named i0, i1, i2 and so on; add and remove them with the + and - buttons. Type the formula for the result and click Apply, or click elsewhere. For example, the normalised difference of two bands is:

(i0 - i1) / (i0 + i1)

You may use numbers, the inputs, the constants pi and e, the operators + - * /, comparisons, &&, ||, !, the choice a ? b : c, and the functions listed under Functions in the node's settings, such as sqrt, pow, log, abs, min, max and clamp. Use pow(a, b) for powers and mod(a, b) for remainders. If any input has no value the result has no value.

A formula that cannot be understood is reported under the box as you type, and on the node once applied.

Sun Shading

A Sun shade node lights a surface from a distant sun, so that slopes facing the sun are light and slopes facing away are dark. Link a grid band to its Surface input and link its Shade output to the Shade input of the Image node. The Sun shaded pseudocolour (wet) preset is set up this way, with the same band coloured and shaded. To drape the colours of one grid over the relief of another, a magnetic grid over an elevation model say, link the Surface input to a second Grid input instead.

Drag the sun around the circle in the node's settings. The circle is the sky seen from below with north at the top: the centre is overhead and the rim is the horizon. Double click the circle to return to the usual sun in the north-west, halfway up the sky. Azimuth and Inclination show the same position in degrees and can be typed.

• Azimuth is the direction the light comes from. Features running across it stand out, especially under a low sun, while features running along it all but disappear, so try more than one direction.
• Inclination also sets how hard the shading is. A low sun shades gentle relief hard; a high sun shades it softly. A high sun also gives a wet look: slopes facing the sun reach white, like a sheen on a wet surface, while the shadowed side darkens only gently. The Sun shaded pseudocolour (wet) preset puts the sun at 65° for this sheen. Lower it towards 45° for plain hillshading with no sheen, or raise it for more.
• Strength multiplies the shade: the same pattern of light and shadow, fainter below 1 and harder above it.

Vertical scale multiplies the surface's values before its slope is measured. Raise it to bring out gentle relief. A grid whose values are not heights - a magnetic grid, say - has no natural slope, so change the vertical scale by factors of ten until the shading looks right.

The shade is 0 on level ground, 1 on a slope that faces the sun square on and -1 on a slope turned edge-on to the sun's rays. Level ground keeps exactly the colour its value was given; the Image node darkens the colour towards black as the shade falls towards -1 and lightens it towards white as it rises towards 1. Slopes turned beyond edge-on give a shade below -1, which the Image node clips, so if very steep ground goes flat black, put a LUT between the Sun shade and the Image and Autotune it to spread the whole range of the shade. The shade is a value like any other: a LUT between the Sun shade and the Image softens or hardens the shading, and an Equation can combine two suns.

The slope is measured in ground units, so a hillside is shaded the same however far you zoom in or out, and the saved image is shaded as the screen is. Zoomed out, relief too fine to see is averaged away, as it is in the colours.

Grid Outputs

For grid arithmetic without an image, Grid Maths gives the same nodes in a window of their own.

A Grid output node turns the Imager into a grid calculator: link any value to it - the result of an Equation, a LUT, a Sun shade - and that value is written as a new grid file when you export. The image is untouched; the node simply keeps the numbers that would otherwise only ever become colours. The normalised difference of two bands, for example, can be saved as a grid of its own with an Equation into a Grid output.

Each value linked to the node becomes one band of the file, and there is always one spare pin beyond the linked ones, waiting for the next band, so several results can go into a single multiband grid. Unlink a band and the pin goes; the bands keep their order. The bands are named after their pins, renamed in the node's settings, and the names are written into the file.

In the node's settings choose the format, the output file, and the cell size, which starts as 0 to take the cell size of the finest grid feeding the node. The line beneath shows the size of the grid those choices make. The grid covers the area of all the grids on the way to any of its bands and carries their coordinate system. Smooth samples the input grids bilinearly between cell centres rather than as blocks, which matters when the output cell is finer than an input's. Build overviews stores reduced resolution copies with the grid. Add to project as a surface loads the written grid into the scene when it is exported.

The grid does not have to wait for an export. Write now writes it to its file straight away, on its own, with the same progress bar and Cancel as an export. Tick Auto write and the node writes its file again, without asking, whenever one of the grids feeding it changes on disk - so a Grid output at the end of a chain keeps up with a preview written by another window, or with a file another program is updating. Grid outputs fed by grids that did not change are left alone.

The node's Value output hands its first band on unchanged, so the chain can carry on from the grid output to a LUT or the Image and the picture shows exactly what is written.

An algorithm can hold as many Grid output nodes as you like, each with its own file, and where a value has no data its band has none. A Grid output that is not ready - no file chosen, nothing linked to it, or several bands in a format that holds one - shows a warning and is simply left out of the export; it never stops the image.

Presets, Loading and Saving

Algorithms are kept in files of their own, with the extension sialg, so one can be used again on other grids or passed to someone else.

• Presets lists the algorithms supplied with Spatial Integration, followed by any you have saved in the algorithmPresets folder of the .si folder in your home folder. A preset keeps the grids you have open.
• Load opens an algorithm file.
• Save writes the algorithm back to its file, and Save as to a new one. An algorithm started from a preset asks for a name the first time.

The name of the algorithm is shown on the toolbar, with a star when it has changes that are not saved. You are asked whether to save them before another algorithm replaces it and before the Imager closes. A grid stored in an algorithm file is remembered relative to the file when the two are close together, so a folder holding both can be moved.

Exporting

Click Export on the toolbar and choose a file for the image. The image is written as a GeoTIFF.

You are then asked for the cell size of the image, which starts as the cell size of the finest grid. A larger cell makes a smaller file; a smaller one makes a larger file without adding detail, since the grids hold none. The size of the image in pixels is shown for the cell size you type, with a warning when it will be very large.

The image covers the area of all the grids the algorithm uses and carries their coordinate system, so it lands in the right place when loaded elsewhere. Where there is no value it is transparent. A progress bar appears under the toolbar while the export runs; Cancel stops it, and a file part way through is not left behind.

Any Grid output nodes in the algorithm are listed in the same dialog, each with a tick to include it, and are written to their own files after the image. Untick Export the image to write only the grids; each already knows its file, format and cell size from its node.