| Environments | PYTHON :: EASI |
| Quick links | Description :: Parameters :: Parameter descriptions :: Return Value :: Details :: Examples :: Related |
| Back to top |
| Back to top |
tieimage(mfile, dbic, searchr, fftsize, minscore, tptarget, roterror, filo, filref, filedem, tieopts)
| Name | Type | Caption | Length | Value range |
|---|---|---|---|---|
| MFILE * | str | Orthoengine project file or a list of image files to examine for multi-ray tie-points. | 1 - | |
| DBIC | List[int] | Input image channel to use for matching | 0 - 1 | Default: 1 |
| SEARCHR | List[int] | Search radius in pixels. | 0 - 1 | Default: 1500 |
| FFTSIZE | List[int] | FFT template matching size | 0 - 2 | |
| MINSCORE | List[float] | Threshold of minimum acceptance | 0 - 2 | 0.65 - 1.0 Default: 0.75 |
| TPTARGET | List[int] | Target number of Tie Points per image | 0 - 1 | |
| ROTERROR | List[int] | Estimated error in rotation | 0 - 1 | |
| FILO * | str | File name of output TPs. | 1 - | |
| FILREF | str | Optional file name of geocoded reference image to use for GCP collection/matching | 0 - | |
| FILEDEM | str | DEM file used to assign heights to GCP's | 0 - | |
| TIEOPTS | str | Processing options | 0 - |
| Back to top |
MFILE
Typically a single Orthoengine project file, which has imagery already ingested, is specified. Alternatively ingested image files with (rough) models attached or ortho imagery can be specified via a directory, a directory with wild card or a list of file names held in a text file (.txt extension). All files should have the same band sequence and projection.
DBIC
Specifies the input band (channel) that contains the imagery to be used in matching. Typically this is the green band, if available.
SEARCHR
Specifies the search radius for matching in pixels. Typically this is on the order of 1000 to 3000 pixels. Larger values take longer to run but are safer to use.
FFTSIZE
Specifies the FFT template matching size in pixels. Options are 32, 64 and 128. A two pass system is used so two FFT sizes are required. Default is 64 for the first and 128 the second.
MINSCORE
The minimum threshold value to use to control acceptance or rejection of a candidate TP as valid. Potential values are from 0.70 (very low) to 1.0 (perfect match). Lower values give more matches but an increased potential of mismatch errors (blunders). Higher values give smaller number of matches but with fewer mismatches. In practice values between 0.73 and 0.80 are most useful. Two values can be specified:
The first controls the acceptance of tie points. The default is 0.75.
The second controls the acceptance of points from the reference image, if specified in FILREF, when GCPs are being collected. The default is 0.75.
TPTARGET
Specifies the target number of TPs desired per image. For good photogrammetric models between 50 and 100 points are needed after block blundle adjustment. Given the number of TPs actually collected is usually less than the target, and even more are removed during block bundle calculations, it is recommended that a target of 150 or higher be used. The default is 150.
ROTERROR
Specifies the estimated unknown rotation (aka Kappa) error between images. This can be from 0 to 45 degrees. If unspecified then a value of 5 degrees is used.
Images in a project have a kappa (heading) value specified. However these kappa values have some level of (rotation) error. Usually this error is quite small, typically less than 5 degrees, so this parameter can be left unspecified. If the error is suspected to be larger (for example with small UAV/drones in windy conditions) then a larger value, up to 45 degrees can be specified. NOTE: A value greater than 5 degrees can signficantly impact performance but may find more tie-points.
If satellite imagery is being used then rotations are typically very well known and this parameter can be left unspecified or set to a value of 5 or less.
FILO
The name of the OE project file or text output file which will contain the tie-points (and GCPs). The output can be either a OrthoEngine project file (.prj) or a text file (.txt). If a project file is specified then the input file (MFILE) must also be a project file.
If a text file is specified as output and GCPs are being collected (via use of the FILREF and FILEDEM parameters), then two .txt files will be produced:
FILREF
Name of reference image file to use for collecting GCP's. Must be the same projection as files specified in MFILE. The same channel as DBIC is used for matching, if this does not exist, then channel one is used for matching.
Note: this file should be roughly the same resolution as the other imagery in the project otherwise few if any GCPs will be collected.
FILEDEM
Name of reference DEM file for height information when collecting GCPs (that is, when FILREF is used). Channel one is assumed to have the elevation data in metres. Any projection and resolution can be used.
TIEOPTS
Specifies special processing options. Typically, you need not specify a value for this parameter.
| Back to top |
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.
| Back to top |
TIEIMAGE is an program used to find Tie Points (TPs) and, optionally, Ground Control Points (GCPs) between a set of images. TIEIMAGE uses FFT Phase Matching to find matching points.
Fast Fourier Transform (FFT) phase matching and Feature Based Matching (FBM) are two powerful matching techniques. TIEIMAGE uses FFT phase matching, while FBM (using the Scale Invariant Feature Transform or SIFT technique) is also availabe using alternative PPFs (FBMEXTRACT and FBMTIE).
When comparing FFT phase matching to FBM matching some advantages of phase matching are: it has more control over match locations and tends to produce a more uniform grid of points; it tends to produce fewer blunders. The disadvantages are it is more sensitive to errors in rotation and scale and thus requires fairly good initial estimations of rotation and limited changes in image scale. Which method to use is dependent on the data. For example - with large format airphoto cameras flown on manned aircraft phase matching is a good choice, for small UAV drones SIFT may be a better choice. In some cases using FBM first and performing a rough alignment, then using phase matching as a second pass can give better results.
The parameter SEARCHR controls the search radius in pixels. It is often unclear what this parameter should be set to since it is dependent on many underlying factors, such as inaccuracies in the initial estimates of image positions, terrain effects and size of imagery itself. For UAV imagery a value of around 2500 is a good default, for large format airphotos (e.g., Ultracam) 2000 and for satellite imagery 1500. Larger search radii will take signficanlty longer to run, and may produce more blunders, but may be necessary if more TPs need to be collected.
The FFTSIZE parameter controls the sizes of the FFT that is used in phase matching. The first value controls the coarse matching step, the second value controls the fine matching step. Values of 32, 64, and 128 are supported. Larger values tend to give fewer blunders, but may not be as accurate and may not find matches when the overlap between images is small. The default is 64, 128: 64 for the coarse match and 128 for the fine match.
The phase matching algorithm generates scores per match between 0 (low) and 1 (high). In practice values below 0.70 are extremely suspect and should never be used. Values above 0.85 are extremely reliable but rare, so insufficent TP's may be collected. A MINSCORE value of 0.75 is a good balance between sufficent TP collection without too many blunders. Values between 0.73 and 0.80 are recommended. The optimal value will vary with quality of the imagery in the project. MINSCORE has two values: the first value controls collection of TPs, the second controls matching for GCP's if a reference image is used (FILREF).
The TPTARGET parameter controls the number of matching attempts, in a regular grid covering the entire image, that will be made. Not all attempts will be successful. For aerial photographs it is good practice to have between 50 and 100 TP's per photo, so a value of 150 is recommended. For satellite imagery between 25 and 50 is good practice, so a value of 100 is recommended. With images that have only narrow overlap much of the grid may be in empty areas then a higher value is recommended, even as high as 300, so at least a few of the attempts fall within the narrow overlap area.
The parameter ROTERROR controls the amount of unknown rotation error between images that can be handled. In many cases, such as satellite imagery, the intial rotation estimates are very good and this parameter can be defaulted or set to 5. With raw UAV images the initial estimates, derived from rough flight directions, can be quite poor and ROTERROR can be set to 15 or more with a maxium of 45. Note that using values greater than 5 degrees will substantially increase processing time, especially as larger angles are used. Note: if very high rotation errors exist it may be better to use Feature Based Matching as a first pass.
A reference image and DEM, parameters FILREF and FILEDEM, can be specified in which case GCP's will be collected simultaneously with the TPs. FILREF must be in the same projection as the project (or input image) projection and should be approximately the same resolution as the imagery. For example, a reference image of 10cm with 15cm imagery will work, but 25cm and 50cm has too much difference. For best results the reference imagery should not be more than a few years difference in time from the project imagery. This capability is targetted at repeat passes of aerial photography separated in time by a few weeks, where a image mosaic is made in the first pass and subsequent collections use the first mosaic to automatically collect GCPs forcing close registration between subsequent mosaics. However this capabilily may be useful in other circumstances, for example, satellite imagery if the resolutions match and the imagery does not differ by more than a few years. The supplied DEM can be of any projection and resolution. For high resolution air borne imagery a DSM (surface model) may be better than a DTM (terrain model).
Hints on Speed
Decreasing the search radius (SEARCHR) and rotation error (ROTERROR) will significantly improve performance. For example halving the search radius will make the matching run almost four times faster. Don't use large values unless absolutely necessary. If UAV images in JPEG format are used, then converting these to uncompressed PIX format can substantially improve performance (though this may substantially increase the disk space used to hold imagery).
Hints on getting more or better matches
| Back to top |
You have an OrthoEngine project file which references a set of airphotos. The project contains the camera model and initial rough orientation for each photo, but has no TPs, which are needed to compute a refined final model. To collect the TPs TIEIMAGE is used:
from pci.tieimage import tieimage mfile = "orthoengine_airphoto_project.prj" dbic = [2] # Green band usually best searchr = [2048] # Large search radius since poor orientation fftsize = [64,128] # Suggested default values minscore = [0.75] # Suggested default values tptarget = [150] # greater than 100 so get enough TPs per image roterror = [10] # compensate for small unknown rotations filo = "project_with_TPs.prj" # new output project with TPs filref = "" filedem = "" tieopts = "" tieimage(mfile, dbic, searchr, fftsize, minscore, tptarget, roterror, filo, tieopts, filref, filedem)
You have an OrthoEngine project file which references a set of SPOT satellite images at 10 metre resolution. You also have a LANDSAT8 15m ortho mosaic of the same area, in the same projection as the SPOT imagery (typically LONG/LAT) that can be used to collect GCPs, as well as a 30m DEM (which can be in any projection) to provide elevations to the collected GCPs. To simultaneously collect TPs and GCPs the following settings are used:
from pci.tieimage import tieimage mfile = "SPOT_satellite_project.prj" dbic = [1] # other bands will work too searchr = [1000] # small since satellites usually accurate fftsize = [64,128] # Suggested default values minscore = [0.75, 0.75] # Suggested default values tptarget = [200] # high to catch points in overlap margins roterror = [] # rotations already known filo = "SPOT_with_TPs_GCPs.prj" # new output project with TPs and GCPs filref = "refdata/LANDSAT8_Mosaic.tif" filedem = "refdata/SRTM_30M_DEM.tif" tieopts = "" tieimage(mfile, dbic, searchr, fftsize, minscore, tptarget, roterror, filo, tieopts, filref, filedem)
You have set of existing ortho images (in .tif format) all in the same projection, in directory f:\ortho. However these have misalignments between them and you wish to create a set of TPs between the images to describe the misalignments. A text file (rather than an OE project file) containing the TPs is required since this will be used as input to a different 3rd party software package:
from pci.tieimage import tieimage mfile = "ortho/*.tif" dbic = [1] searchr = [500] # small since satellites usually accurate fftsize = [64,128] # Suggested default values minscore = [0.75 ] # Suggested default values tptarget = [200] # high to catch points in overlap margins roterror = [] # rotations already known filo = r"ortho_TPs.txt" # text file with TP information filref = r"" filedem = r"" tieopts = r"" tieimage(mfile, dbic, searchr, fftsize, minscore, tptarget, roterror, filo, tieopts, filref, filedem)
© PCI Geomatics Enterprises, Inc.®, 2026. All rights reserved.