Geocorrection & Mapping Options
*******************************

Digital Elevation Model (DEM) Settings
--------------------------------------
**Expected value**: Select one of the three options; if 'Custom DEM' selected, also provide path to DEM file.

The DEM settings will affect how your geolocated data is mapped, and ultimately the accuracy of the results. The 
simpliest (and default) option is to use and ellipsoid model, it does not require any further configuration but it is 
the least accurate option.

If your survey area falls between latitudes 56 degrees South up to 60 degrees North, you can use the Shuttle Radar 
Topography Mission (SRTM) DEM - see the NASA JPL website for more information - https://www2.jpl.nasa.gov/srtm/ This is 
available at 30 metre resolution and the area required will be downloaded from Geona servers during processing so
requires an active internet connection for processing to work successfully. 

For the most accurate results we recommend you provide a custom DEM for your survey site. Geona expects a single-band 
ENVI BIL or BSQ file. The coordinate reference system should use WGS-84 geographic coordinates with elevations in metres 
above the WGS-84 ellipsoid. This is equivalent to the EPSG code: "4326" or PROJ.4 string: "+proj=longlat +datum=WGS84 +no_defs".

Geona requires the DEM to fully cover the flightline when processing. In reality, as Geona doesn't know the full 
flightline coverage prior to geocorrection, the DEM has to cover an area larger than the flightline, to account for a 
window of uncertainty. The DEM must also not contain any gaps.

To use a custom DEM it must first be in the coordinate system and file format as stated above. This can be acheived using
freely available open source tools such as GDAL, GRASS and QGIS, or other GIS systems such as ERDAS Imagine and ArcMap.
A simple command line utility such as `gdalwarp` will be able to do this.

Output Projection
-----------------
The default project is **UTM WGS84** where the UTM zone will automatically be detected from the navigation data. We use the
lower left corner of the extent of the navigation data, .i.e., the minimum latitude and longitude, to establish which
UTM zone to use. If your survey area covers more than UTM zone, it's possible that this is not the best approach, so you
can override this with a user-specified UTM zone to use. 

**Ordnance Survey National Grid (OSBG)** is really only applicable to survey sites in the British Isles.

**Custom Projection** allows you to define any valid projection in PROJ format. Please see 
https://proj.org/en/9.3/operations/projections/index.html for a comprehensive list of possible global projections or 
instructions on how to define a custom, more localised projection. 

.. warning::
  If you provide a custom projection string, it is not validated prior to mapping and so any errors in the custom 
  projection string may cause the mapping stage to fail. 

Bands
-----
By default, the resulting data cube will contain all bands which are present in the raw input data, however, you can 
choose to only map a subest of bands. Mapping fewer bands will be quicker as it is less compute intensive so is a nice
way to generate results for a quick check of the settings used, for example to check geolocation accuracy or :ref:`scan
line time offset values <Time offset to scan lines>`

**3-Band options** are available for RBG, NIR, SWIR and Thermal sensors. In each case, just 3 bands will be mapped from 
the full range of wave bands; those closest to the wavelengths detailed in the table below are used.

.. list-table:: Selected wavebands for 3-band options
    :widths: auto
    :header-rows: 1

    * - 3-Band option
      - Wavelengths 
    * - RGB true colour
      - 640, 540, 470
    * - NIR false colour
      - 800, 640, 540
    * - SWIR false colour
      - 1750, 1400, 1175
    * - Thermal false colour
      - 10510, 10014, 9518

**Custom band list** provides the opportunity to specify exactly which bands you would like to include in the output 
data cube. Provide band numbers (not wavelength values) as a comma separated list of individual band numbers and/or a 
range. The band number is a zero indexed list, so the first band is band 0. If you request bands outside the extent of 
the list you will get an out-of-range error and the mapping will fail. 

Pixel Size
----------
**Expected value**: (required) floating point value

This value determines the pixel size on the ground measured in metres.

.. note::
    This field is automatically set if you upload a :ref:`Sensor Lookup File <Sensor Lookup File>`

Output X and Y grids
--------------------
It may be useful to have the X and Y mapping grids output as separate bands. If so you can select this option to create two new BIL files containing these grids.

Output row/column mapping
-------------------------
When mapping with nearest neighbour interpolation it is possible to output the pixel mapping of the mapped image. This is a two band BIL file that contains a band of
row mappings and another of column mappings. That is, the level1 pixel position (row,col) is gridded to the output map.

Area
----
**Expected value**: (optional) 4 or 6 space separated integers

It is possible to only map a region of interest - you can enter that here. It is also possible to define the number of rows and columns
of the final mapped image here rather than using the `Pixel size` option above. The order of items is minX maxX minY maxY rows cols
where rows cols are optional.

Interpolation
-------------

Sets the resampling interpolation method. Choose between:

* Nearest neighbour
* bilinear
* cubic spline
* inverse distance weighted

Maximum interpolation distance
------------------------------
**Expected value**: (optional) floating point number in metres

Set the ground distance over which to interpolate. A large number will ensure there are no holes but will slow the process. A low number will be quicker but could leave holes in the
mapped data if it is of similar size to the resolution. The default (left empty) allows Geona to autodetect a suitable value based on the input data.

Buffer size
-----------
**Expected value**: (required) integer in megabytes

Additional memory that can be used to speed up the mapping procedure (in MB). The default is to use 1024 MB (1 GB) and this is additional to other overheads within Geona (i.e the
memory usage will be larger than this). This buffer is for storing the level1 data in. The higher the value used, the more RAM Geona will try to use (if required) for storing
the level1 data in, and the faster the processing will go. Selecting a high value risks slowing other processes running on the computer or potentially causing a crash if there
is not enough free memory for critical operations.

Output data type
----------------

Select the type of the output data. This ranges from 8-bit upto 64-bit and can be signed or unsigned. Note that selecting an output type lower than the input type
can cause truncation. E.g. mapping a floating point dataset to integer will give unexpected results.

* uchar8 - for 8-bit unsigned data.
* int16 - for 16-bit signed integer data.
* uint16 - for 16-bit unsigned integer data.
* int32 - for 32-bit signed integer data.
* uint32 - for 32-bit unsigned integer data.
* int64 - for 64-bit signed integer data.
* uint64 - for 64-bit unsigned integer data.
* float32 - for 32-bit floating point data..
* float64 - for 64-bit floating point data..

Ignore scan lines
-----------------
**Expected value**: (optional) space separated list of integers

If some level1 scanlines look erroneous and should not be included in the map product then you can add a space separated list of lines to ignore here.

Ignore value
------------
**Expected value**: (optional) integer

Data in the level1 file with a particular value are ignored in the mapping. The default is values of 0, such as those that have been masked in earlier stages.

Define 'no data' value
----------------------
**Expected value**: (optional) integer

The default no data value, the value specifying no data in the mapped product, is 0. To change this enter a new value here.

Disable airplane assumption
---------------------------

Some assumptions based on airplace platforms can be are made to speed up the mapping process, but these are not valid for drone platforms. If mapping drone data then select this option.
If you suspect that parts of the flight line are not being mapped then you can also select this option to double check it's not being missed because of these assumptions.