COMPOSITE

Description

Parameters

Parameter descriptions

MFILE

List of geocoded image files. This can be a directory, a directory with wild card or a list of file names held in a text file (.txt extension). All files must have the same projection, and resolution.

DBIMAGE

Specifies the imagery channels (bands) that should be contained in the output mosaic. If unspecified an attempt will be made to automatically identify image bands using wavelength metadata (MaxWavelength and MinWavelength) associated with each band.

Ranges of channels or segments can be specified with negative values. For example, {1,-4,10} is internally expanded to {1,2,3,4,10}. When you are not specifying a range in this way, only 48 numbers can be specified explicitly.

MFILEMSK

List of files containing mask information. This can be a directory, a directory with wild card or a list of file names held in a text file (.txt extension). All files must have the same projection, resolution and bitmap or image band sequence. It is assumed that for every image specified by MFILE a corresponding file is specified by MFILEMSK. If MFILEMSK is unspecified then it is assumed the bitmap or class/quality layer is in the same file as the imagery data.

DBICMASK

Specifies the input band (channel) that contains the quality or class information to be used to identify clouds. Usually these bands are created by the ARD process. If MFILEMSK is not specified then this band is assumed to be in the same file as the imagery.

If unspecified then no quality or class information channel will be used. If a 0 (zero) is specified this indicates that the quality channel should be automatically determined by looking for the metadata tag BandDescription = "Pixel Quality" or the words "Pixel Quality" in the channel description.

MASKVALS

Only required if DBICMASK is specified. Up to 16 values can be used. If unspecified then metadata tags in the DBICMASK specified channel will be scanned to determine cloud related values. LANDSAT and PCI ARD metadata tags are supported. Pixels under mask values will not be used.

DBIB

Specifies the segment number of the bitmap to use as an exclusion mask. Typically this bitmap is a cloud mask. If MFILEMSK is not specified then this bitmap is assumed to be in the same file as the imagery.

FILO

The name of the output file. If this file does not exist then one will automatically be created covering the entire extents of the data with the same projection and resolution as the input imagery.

If the file already exists then it will be deleted, however its extents will be used in creating a new output file rather than the full extents of the input imagery data. This is useful in specifying an area of interest smaller than the full extents.

COMPMETH

The compositing method that should be used in generating the mosaic.

DBICNDVI

Specifies the NIR and RED input channels that should be used to compute NDVI values when the COMPMETH is set to NDVI or MINNDVI.

If DBIMAGE is unspecied (automatic image band detection mode) then DBICNDVI can also be left unspecified, in which case the best NIR and RED bands will be automatically determined.

DATETO

Specifies the latest date of images to include. Any images after this cutoff date will be excluded from processing. If unspecified this parameter is ignored. The numeric values are in the order: day, month, year. The date an image was acquired is determined using the metadata tag "Acquisition_DateTime".

DATEFROM

Specifies the earliest data of images to include. Any images before this date will excluded from processing. If unspecified this parameter will be ignored. The numeric values are in the order: day, month, year

DAYSPAN

Specifies the number (or span) of days centred on a target day of year that should be used. The numeric values are in the order: day, month, number of days. The first two values give the target date as day, month, and the third value gives the total number of days centred on this date. For example: 18,6,20 would mean the date is June 18 and any images between June 8 and June 28 would be included, regardless of the year. This is very useful in creating seasonal composites, for example, spring or summer, covering multiple years. If unspecified, this parameter is ignored.

COMPOPTS

Specifies special processing options. Typically, you need not specify a value for this parameter.

MONITOR

The program progress can be monitored by printing the percentage of processing completed. A system parameter, MONITOR, controls this activity.

Available options are:

• ON: Turns the monitor ON (default)
• OFF: Turns the monitor OFF (recommended if running in batch or background mode)

Details

COMPOSITE merges a set of overlaping geocoded images into a mosaic using one of number of pixel by pixel compositing techniques. Typically the input data set has a deep 'stack' of images at each location, from different dates, and an exclusion mask (usually indicating clouds) for each image showing where data should not be used. During the compositing each pixel location is examined independently to determine the best value to use, either by copying the pixel from a particular image (e.g., maximum NDVI compositing) or computing a value from some of the images (e.g., Geomedian compositing). One common usage of COMPOSITE is to create cloud free mosaics.

COMPOSITE differs from other mosaciking techniques (such as MOSPREP/MOSRUN) that rely on finding cutline (vector) boundaries between images and then assembling the output mosaic like a large jigsaw puzzle. The cutline techniques are best in situations where there are few images to work with (e.g., only one or two images overlap any particular area) or have large viewing geometry differences between them, like aerial photography. Compositing is useful for satellite imagery (especially lower resolution satellites) where there can be a stack of hundreds of images over any particular area (for example, Landsat or Sentinel archives).

The inputs to COMPOSITE are expected to be already color balanced, ortho corrected to the same projection and resolution, and (optionally) have pre-generated masks indicating exclusion areas for each image. Typically these images are in Analysis Ready Data (ARD) form and the exclusion masks are the quality or spectral class layers automatically created when the raw imagery is processed via ARD software. The metadata tag "Acquisition_DateTime" (if available) in each image is decoded to get the image date.

One feature of COMPOSITE is the ability to do simple queries on the data based on date using the DATETO, DATEFROM and DAYSPAN parameters. Imagine a directory with 5,000 satellite images taken every couple of weeks covering a time period from the year 2000 to 2020. At each location there are many hundred's of images. It is possible to just use images from a range of years (say, 2010 to 2012) and even particular months (say, May and June) within a range of years. This can make it easy to create special individual composites like a summer maximum NDVI composite for each year from 2000 to 2020, without having to specifically list out the image file names that fit the criteria.

In addition to the composite mosaic a number of extra information bands and a text report are automatically created. These are the Image ID band, which identifies which image every pixel came from (where possilbe), a Quality band which gives the status of each pixel (for example, if it was good data or if the pixel was masked in every image and is of suspect quality) and the NDVI value (if NDVI compositing was used). A text report also is created that provides processing details and connects the image id's in the ID band to specific file names. This information can be very useful tracking processing history and provenance, or identfiying pixels of suspect nature during follow on analysis. If unwanted these layers can be suppressed using the "noextra", "noid", "noquality", "nondvi" and "noreport" options in the COMPOPTS parameter.

Parameter MFILE specifies the location of the input images. This can be a single file, a directory, a path/filename using * as a wildcard, or a text file with an explicit list of file names. All input files must be of the same resolution and projection.

DBIMAGE specifies the image channels (bands) in MFILE that will be used for the output mosaic. If specified then it is assumed that ALL the files have the same band order. If unspecified an 'automatic' mode is activated where each band in each file is identified using its metadata tags, MaxWavelength and MinWavelength. Bands without this wavelength metadata are ignored. Across images the wavelengths are matched to corresponding wavelengths automatically using maximum overlap. This means that the image bands do not have to be in the same order, may have somewhat different min/max wavelengths, and in fact some images may have extra bands. After the matching the smallest subset of bands that exists in all images is used. This option is extremely useful in archives where over time slightly different sensors were available, such as the Landsat or SPOT series where over a 40 year history the number of bands increased and their order on disk were rearranged. NOTE: the smallest number of bands is determined by using all the input images BEFORE any are excluded via date restrictions.

MFILEMSK specifies the location of the input exclusion masks. This can be a single file, a directory, a path/filename using * as a wildcard, or a text file with an explicit list of file names. It is assumed for each input image in MFILE there is a corresponding file in MFILEMSK. Input files in MFILE and MFILEMSK are matched up via similarity in file names. If MFILEMSK is unspecified then it is assumed mask information is in the same file as the imagery.

DBICMASK and DBIB provide the location of the quality/class layers and/or bitmaps to use as exclusion masks. It is possible to specify either one or both. If DBICMASK and DBIB are both unspecified then the mosaic can still be generated but clouds or poor quality pixels may be present in the mosaic.

DBICMASK specifies the channel (band) containing ARD quality or spectral class information for clouds. For PCI ARD quality layers class values 30 (cloud) and 50 (cloud shadow) are automatically detected and used. For PCI ARD spectral class maps values 10, 12 (thick cloud), 14 (cirrus cloud), 16 (thin cloud) and 24 (cloud shadow) are automatically detected and used. Landsat Quality layer values are also automatically detected. NOTE: If different values are needed then these can be specified in the MASKVALS parameter. For example: MASKVALS = 27, 96, 105 would exclude values 27, 96 and 105. The text report in the output composite file can be examined for a list of exclusion values actually used.

If DBICMASK is set to 0 (zero) a special mode is invoked where the quality band is automatically found by looking for the words "Pixel Quality" in the band description. This is useful if the images are a mixture of different sensors (e.g., SPOT 2 and SPOT 6) and the quality band is not in a single fixed location (e.g., in some images it is in band 4 and other images in band 7). Using a zero for DBICMASK is useful when used in conjunction with automatic band wavelength matching for parameter DBIMAGE.

DBIB specifies the bitmap segment number holding the bit map exclusion (cloud) mask. A set bit means that pixel position should be excluded.

FILO specifies the name of the output file that will contain the completed mosaic. If this file does not already exist, then it will be created with the same projection and resolution as the input imagery and with extents covering the entire area covered by all the input imagery. If the file already exists, it will be deleted, however its extents will be saved and used when the new file is created. This provides a way of specifying a smaller Area of Interest (AOI) within the larger extents and can be much faster to process and take up far less output disk space. The output file will be in .PIX format.

The COMPMETH parameter specifies which compositing method ahould be used. Available options are: average, geomedian, geomedoid, (max) ndvi, minndvi, and date. The most commonly used options are geomedian and ndvi.

The "average" composite method computes the average of all of the (unmasked) image pixels. Its advantage is speed and simplicity, but can easily be contaminated by clouds. It is not commonly used.

The "geomedian" composite method computes the geometric median (which is the point minimizing the sum of distances to the input pixels), also known as the spatial median, or Torricelli point. This value is an iteratively computed synthetic value (i.e., is not a copy of one of the actual input image pixels). Its advantage is it can create cloud free mosaics even when up to half the input images contain clouds and often can be used even without cloud masks (in a quality or bitmap layer). The disadvantage is it can slow to compute and the computed pixel values are not 'true' measurements.

The "geomedoid", or geometric medoid, composite method is very similar to the geometric median except an actual pixel from one of the images which minimizes the distance is selected rather than a computed synthetic value. The advantage is that the pixel is a true measurement and may offer benefits in follow on anaylysis, the disadvantage is the mosaic may look 'patchy' compared to the geometric median and is not as good for visual presentation.

The "ndvi", or maximum NDVI (Normalized Difference Vegetative Index) composite method selects the image pixel at each location which has the maximum NDVI value. NDVI is defined as NIR-RED/NIR+RED where NIR is a near infrared band (wavelength 0.75um to 2.5um) and RED is the red band (0.62um to 0.75um). This allows for composites to be created that have the maximum vegetation at every pixel and is useful for crop analysis, forestry and other applications. The NDVI band is automatically saved along with the selected imagery bands. This method is relatively insensitive to clouds.

The "minndvi", or minimum NDVI composite method is the same as maximum NDVI method except it selects the image pixel at each location which has the minimum NDVI value.

The "date" compositing method uses the newest available (unmasked) image at each pixel. This method is computationally fast but very prone to cloud contamination and can have noticable seam lines between images. However it can create mosaics that have the most up to date imagery available. It is highly advisable to have excellent cloud masks if this option is used.

The parameter DBICNDVI specifies the NIR and RED channels when the ndvi or minndvi compositing methods are selected via COMPMETH. The first value is the NIR band and the second is the RED band. If automatic band wavelength matching is being used (DBIMAGE is unspecified) then DBICNDVI should also be left unspecified and the proper NIR and RED bands will be selected.

The DATETO, DATEFROM and DAYSPAN parameters allow selection of a subset of the images based on date. It is assumed that the date of each file is contained in the metadata tag "Acquisition_DateTime" in the form "YYYY-MM-DDTHH:MM:SS.SSSSSSZ" (e.g., "2005-05-02T08:34:20.119000Z".

If the DATETO parameter is specified then all images acquired after this date will be ignored. If the DATEFROM parameter is specified then any images acquired before this date will be ignored. Dates are specified in the form day, month, year. For example: 15,6,2008 is 15th of June, 2008.

The DAYSPAN is used to create 'seasonal' images. If specified then imagery is limited to a certain number of days around a particular day of year. Three values are specified: day, month, span of days. For example, if DAYSPAN= 15, 9, 20 then this means images between 5th of September and 25th of September would be selected, regardless of the year. If DAYSPAN=15, 9, 60 then images between 15th August and 15th October would be selected.

The COMPOPTS parameter can be used to control less commonly used options. These options are described in more detail the COMPOPTS descripiton above.

PREPARING MULTI-SENSOR DATA SETS FOR AUTOMATED PROCESSING

If the entire data set contains imagery from a single sensor then the image band positions are fixed (for example the first band is always Red, the second Green, ...), and the quality band is always in the same location etc... In this case the DBIMAGE, DBICMASK, DBICNDVI parameters can be explicitly set.

Examples

Example 1:

You have a set of overlaping geocoded satellite images (project/*.pix in a stack covering many years and want a cloud free mosaic. Though some of the images have some clouded areas the majority of them are cloud free so the geometric median composite method can be used without the need for any cloud masking. All files have the same projection and resolution and each file has RGB imagery in bands 1, 2, 3. Since all imagery should be used the the DATETO, DATEFROM and DAYSPAN parameters are left unspecified.

EASI>MFILE     = "project\*.pix"
EASI>DBIMAGE   = 1,2,3
EASI>MFILEMSK  = ""
EASI>DBICMASK  = 
EASI>MASKVALS  =
EASI>DBIB      = 
EASI>FILO      = "RGB_median_mosaic.pix"
EASI>COMPMETH  = "MEDIAN"
EASI>DBICNDVI  = 
EASI>DATETO    = 
EASI>DATEFROM  = 
EASI>DAYSPAN   = 
EASI>COMPOPTS  = 
EASI>RUN COMPOSITE

Example 2:

You have an archive of overlaping geocoded satellite images (archivestack/*_ortho.pix). Four image bands are available in the order: red, green, blue and NIR. These images were acquired every two weeks and cover a 10 year time period from 2010 to 2020. The images are in Analysis Ready Data state with each image having a separate quality layer file (archivestack/*_QUALITY.pix)which identifies ground classes as well as clouded pixels (indicated by values 30 for cloud shadow and 50 for cloud). A maximum NDVI mosaic is desired using three years of data from 2014, 2015 and 2016 for the months of May and June (a span of 60 days around 30th of May). The NDVI is computed from the NIR and Red bands (4 and 1). The image ID and quality layers will be added as extra bands after the imagery in the output mosaic file. A dilation of 5 pixels around clouds is requested to remove fringes.

EASI>MFILE     = "archivestack/*_ortho.pix"
EASI>DBIMAGE   = 1,2,3,4
EASI>MFILEMSK  = "archivestack/*_QUALITY.pix"
EASI>DBICMASK  = 1
EASI>MASKVALS  = 30, 50
EASI>DBIB      = 
EASI>FILO      = "maxNDVI_mosaic_June_July_2014_to_2017.pix"
EASI>COMPMETH  = "NDVI"
EASI>DBICNDVI  = 4, 1
EASI>DATETO    = 31,12,2016
EASI>DATEFROM  =  1, 1,2014
EASI>DAYSPAN   = 30,5,60
EASI>COMPOPTS  = "dilate=5"
EASI>RUN COMPOSITE

Example 3:

You have a large archive of overlaping geocoded satellite images (mixed_sensor_archive/*.pix which contains images from different sensors, including SPOT2, SPOT5 and SPOT7. The images from each sensor have varying numbers bands and the order of band wavelengths differ. However each band has metadata tags identifying the min and max wavelength (MinWavelength and MaxWavelength). A pixel quality band exists in most files, identified by the words "Pixel Quality" in the band description, and within this band the mask values 10 and 30 indicate clouded and heavily clouded pixels. The images cover a 20 year period from 2000 to 2020 and the "Acquisition_DateTime" metadata tag in each image providesthe date and time the satellite image was acquired.

Given this archive you want to create a composite mosaic for the summer of 2012 and the summer of 2013, where summer is considered the months of June, July and August. This mosaic use will be for visual purposes rather than analysis. By leaving DBIMAGE unspecified and setting DBICMASK to zero (0) the sensor bands will automatically be mapped across different satellites and the quality mask located. Since this area has a lot of clouds it is possible that some locations will be cloudy in all images which could leave visually displeasing 'holes' in the mosaic. By using the 'fill' option in the COMPOPTS parameter these areas will be filled in with cloudy information, not ideal, but better than having a hole. In addition, given this is going to be used for visual purposes only the extra output bands giving image ID and quality per pixel are not required so they are switched off using the 'noextra' option, saving disk space.

EASI>MFILE     = "mixed_sensor_archive\*.pix"
EASI>DBIMAGE   = 
EASI>MFILEMSK  = ""
EASI>DBICMASK  = 0
EASI>MASKVALS  = 10, 30
EASI>DBIB      = 
EASI>FILO      = "summer_2012.pix"
EASI>COMPMETH  = "MEDIAN"
EASI>DBICNDVI  = 
EASI>DATETO    = 1, 6, 2012
EASI>DATEFROM  = 31,8, 2012
EASI>DAYSPAN   = 
EASI>COMPOPTS  = "fill noextra"
EASI>RUN COMPOSITE
EASI>FILO      = "summer_2013.pix"
EASI>DATETO    = 1, 6, 2013
EASI>DATEFROM  = 31,8, 2013
EASI>RUN COMPOSITE