SUPERMATCH

Description

Parameters

supermatch(fili, dbic, loclmask, filref, dbic_ref, refmask, searchr, searchun, fftsize, minscore, pntgrid, pntstrat, pntclean, filo, pointapp)

Parameter descriptions

FILI

This parameter specifies the name of the input geocoded orthorectified file to process. This file can be a GDB-supported raster format.

DBIC

Specifies the input bands (channels) that contains the imagery to be used in matching. Typically this is a single band, but up to three bands can be specified. If extra bands are specified then matching is attempted on all bands and the results are used to cross check for blunders potentially resulting in better accuracy, though at the cost of significantly higher processing time. Regardless of the number of bands specified only a single set of output X/Y offsets is produced.

LOCLMASK

Specify whether to apply a local mask to prevent points from being collected in those locations in FILI. If no value is specified for this parameter (default) no local exclusion mask will be applied.

LOCLMASK = (NONE | BIT | VEC | <n>)

You can specify the value of LOCLMASK using the following:

• NONE: exclude no pixels from the computation
• BIT: use a bitmap segment as the mask. If there are multiple bitmaps, the last one is used. All image pixels covered by the bitmap are excluded from point collection.
• VEC: use a vector segment as the mask. If there are multiple vector segments, the last one is used. This vector segment must be a polygon, and all image pixels enclosed by the polygon are excluded from point collection.
• <n>: specifies a particular segment number that contains the desired mask segment to be used.

This parameter is optional.

FILREF

Geocoded reference ortho image(s) to match against. This can be a single file name, directory path with wild card, or name of a text file (.txt) that contains the names of files. These files should have the resolution as FILI for best results.

DBIC_REF

Specifies the input band (channel) that contains the imagery to be used in matching.

REFMASK

Specify whether to apply a local mask to prevent points from being collected in those locations in FILREF. If no value is specified for this parameter (default) no local exclusion mask will be applied.

REFMASK = (NONE | BIT | VEC | <n>)

You can specify the value of REFMASK using the following:

• NONE: exclude no pixels from the computation
• BIT: use a bitmap segment as the mask. If there are multiple bitmaps, the last one is used. All image pixels covered by the bitmap are excluded from point collection.
• VEC: use a vector segment as the mask. If there are multiple vector segments, the last one is used. This vector segment must be a polygon, and all image pixels enclosed by the polygon are excluded from point collection.
• <n>: specifies a particular segment number that contains the desired mask segment to be used.

This parameter is optional. If specified then ALL reference files must contain the same type of mask data.

SEARCHR

The size of the area to search in the reference image. The unit of measure for this value is determined by the value of Search radius units(SEARCHUN). Typically this is a small value such as 16 pixels since ortho images already should be well aligned. If the ortho images are aligned poorly then larger values may be more appropriate, however this will take significantly more processing time.

SEARCHUN

The unit of measure of the value of Search radius(SEARCHR).

Acceptable values are as follows:

• PIXEL:search radius in pixels
• METER:search radius in meters
• FEET:search radius in feet
• US_FEET:search radius in U.S. Survey feet

FFTSIZE

Specifies the FFT template matching size in pixels. Options are 32, 64, 128, 256, 512. The default is 64. Larger sizes tend to have fewer blunders, but are less precise and run slower. If two sizes are specified then the second (smaller) size is used to refine the match.

MINSCORE

The minimum threshold value to use to control acceptance or rejection of a candidate match points. Reasonable values are from 0.73 (low) to 1.0 (perfect match). Default is 0.75. Larger values ensure more accuracy but can result in fewer (or no) match points. Lower values result in more matches but can have higher levels of blunders (mismatches). If the ortho images are very similar (e.g., taken a few days apart) then a higher value (e.g., 0.85) can be used.

PNTGRID

Specifies the point grid spacing, in pixels, on the image for matching. Values between 1 and 500 are supported and typically a value between 20 and 50 is used. Smaller grid spacings can model finer mismatch detail, but take longer to run. In most cases a value of 25 is a good balance between detail and running time. If the ortho imagery is far apart in time (for example 5 years) and look quite different, a smaller grid may be necessary since many of the grid locations may fail to find a match.

PNTSTRAT

The strategy that should be used for matching points when multiple reference images are specified in FILREF. FIRST means that the first reference image that covers an area will provide match points and no other matches will be tried in that area afterwards. BEST means that best scoring match point will be choosen regardless of which reference image it comes from. If a single reference image is used then FIRST and BEST are equivalent. FIRST is the default.

The FIRST strategy is fastest and allows reference imagery to be ordered via priority if they are listed in in a .txt (or .mfile).

The BEST strategy ensures that as many points as possible are collected with the highest score (i.e., quality) but can be slow to compute and can result in adjacent points matching from different reference images. This may introduce 'jitter' if the reference images themselves are not perfectly aligned.

PNTCLEAN

Level of filtering that will be applied to the match points. This removes blunders and smooths the results. Supported options are: NONE, OFF, LO(W), MED(IUM) and HI(GH), AUTO(MATIC), QA. OFF and NONE are equivalent and switch all filtering off. AUTO applies a medium or heavy filter depending on image statistics. PL is a special mode that accepts large local variances typical of camera lense distortion. QA is intended for circumstances where SUPERMATCH is being used to quantify the difference between two images. The QA option applies blunder filtering options tuned for QA analysis.

FILO

The name of the output file, which is automatically created, that will contain information on the matching process and results. This file consists of two 32 bit real output imagery bands, containing the X and Y matching offsets (shifts) between the ortho image and the reference image. Optionally two vector segments containing the actual match points can be appended (see POINTAPP parameter).

POINTAPP

Specifies whether to append the actual match points in a vector segment if, for some reason, they are needed for further analysis. Supported options are: YES (to have points appended) and NO (default) and ALL. If ALL is specified extra raster bands are created, in addition to the match points, giving other processing information.

Return Value

Returns: Processing Statistics

Type:  PCI_DOUBLE

Parameter: imstat

Upon completion the return value contains a collection of floating point values representing processing statistics and metrics. The contents of the collection are described in the function details, processing statistics section, below.

This information may be valuable in scripts that attempt to make informed decisions as to whether the matching processes was necessary or perhaps should be rerun with different settings. For example - if the average absolute offset is very small (say less than 1/10 th of a pixel) the alignment may already be so good that the imagery can be left as is.

Details

When two ortho images are laid on top of each other they should perfectly align, in theory at least. In practice there are often small shifts of a fraction of pixel and in particularly bad cases this can be many pixels. This misalignment can be caused by poor math models (e.g., by using inaccurate GCPs), a low quality elevation model or distortions in the camera lense. Poor alignment can make some types of analysis, such as change detection, very difficult. Ideally alignment errors should be corrected at the source and the ortho's regenerated with more accuracy. However in many cases this option is not available and it is necessary to find the misalignments and correct them as a separate process.

SUPERMATCH is an algorithm used to find match points between a match image and a set of reference images. The output of this algorithm is a file that contains the shift (offset) between the match image and the reference images held in two channels, one channel giving the X shift and the second giving the Y shift. These bands can be passed to the SUPERAPPLY algorithm which will apply and resample the match image using the offsets, resulting in a new match image which is more closely aligned with the reference images.

In addition to the X and Y shift bands two vector segments can optionally be created. The first vector segment contains all of the raw matching points before any filtering and the second contains the 'good' match points used in creating the shift bands. These vector segments can be used as input to more sophisticated or alternative blunder detection and/or smoothing algorithms if these are available.

The match image and references images must be the same resolution (within 5%), but can be in different projections. In areas where matching in not desired, for both the match and reference images, masks (e.g., clouds or water) can be used to prevent matching. The shifts in these areas will be interpolated from matches surrounding the masked area.

Upon completion the return value (IMSTAT in EASI) contains the following processing information and statistics, in the order given. These values are also provided as meta data in the output file (FILO). Distances are in FILI pixels.

1. Number of good match points (meta data tag shift_number_matched_points)
2. Number of unused low score match points (shift_number_failed_match_points)
3. Number of blunders detected
4. Number of match locations excluded by the exclusion masks (shift_number_masked_points)
5. Number of match locations that were outside any reference data (shift_number_no_ref_data_points)
6. Average score of good match points (0.0 is low, 1.0 is high) (shift_score_mean)
7. Sigma of score (shift_score_sigma)
8. Average offset, X direction (shift_mean_X)
9. Average absolute offset, X direction (shift_absmean_X)
10. X Direction offset sigma (shift_sigma_X)
11. X Direction RMSE (shift_RMSE_X)
12. Average offset, Y direction (shift_mean_Y)
13. Average absolute offset, Y Direction (shift_absmean_Y)
14. Y Direction offset sigma (shift_sigma_Y)
15. Y Direction RMSE (shift_RMSE_Y)
16. Average radial offset (i.e., root(X**2 + Y**2) (shift_mean_radial)
17. Radial sigma (shift_sigma_radial)
18. Radial CE95 = 2.4478 * 0.5 * (RMSE_X + RMSE_Y) (shift_CE95)
19. Radial CE90 = 2.1460 * 0.5 * (RMSE_X + RMSE_Y) (shift_CE90)
20. Radial RMSE (shift_RMSE_radial)
21. Average X error in map units (map_mean_X)
22. X RMSE in map units (map_RMSE_X)
23. Average Y error in map units (map_mean_Y)
24. Y RMSE in map units (map_RMSE_Y)
25. Average Radial error in map units (map_mean_radial)
26. Radial RMSE in map units(map_RMSE_radial)
27. CE90 in map units = map_RMSE_radial*1.645 (map_CE90)
28. CE95 in map units = map_RMSE_radial*1.960 (map_CE95)
29. CE90 in map units using sorted radial map errors (map_CE90_using_sort)
30. CE95 in map units using sorted radial map errors (map_CE95_using_sort)

A form of accuracy assesement can be generated by running SUPERMATCH, applying the correction via SUPERAPPLY and then running SUPERMATCH on the resulting corrected image (using a different PNTGRID value, typically a prime number, to ensure different sampling locations). The resulting statistics should give an accuracy estimate. NOTE: two sets of values are generated - ones based on shifts used to resample imagery (e.g., shift_RMSE_radial) and one giving the error in map units (e.g., map_RMSE_radial). These are not equivalent. For accuracy assessment the statistics in map units should be used.

Example

You have two overlaping geocoded ortho images in the same projection and wish to ensure they are perfectly co-registered.

from pci.supermatch import supermatch

fili = "match_ortho.pix"
dbic = [1]
loclmask = ""
filref = "reference_ortho.pix"
dbic_ref = [1]
refmask = ""
searchr = [32]
searchun = "PIXEL"
fftsize = [64]
minscore = [0.8]
pntgrid = [10]
pntstrat = "FIRST"
pntclean = "AUTO"
filo = "offsets.pix"
pointapp = "OFF"

imstat = supermatch(fili, dbic, loclmask, filref, dbic_ref, refmask, searchr, searchun, fftsize, minscore, pntgrid, pntstrat, pntclean, filo, pointapp)