TORTHO

True orthorectification of imagery


EnvironmentsPYTHON :: EASI :: MODELER
Quick linksDescription :: Parameters :: Parameter descriptions :: Details :: Example :: Related

Back to top

Description


With TORTHO, you can create true-orthorectified images during ortho-image production.
Back to top

Parameters


tortho(mfile, dbic, mmseg, dbiw, srcbgd, radiodif, outdir, ftype, foptions, outbgd, edgeclip, mapunits, bxpxsz, bypxsz, tipostrn, filedem, dbec, backelev, elevref, elevunit, elfactor, filedbm, dbmpxerr, dbvs, zref, zunit, zfactor, resample, algo, proc)

Name Type Caption Length Value range
MFILE * str Input-file name, folder (directory), or text file 1 -    
DBIC List[int] Input raster channel(s) 0 -    
MMSEG List[int] Input math-model segment 0 - 1  
DBIW List[int] Input window 0 - 4 XOff, YOff, XSize, YSize
SRCBGD str Source background value 0 -   Default: FILE
RADIODIF str Allowable radiometric difference 0 -   Default: LOW
OUTDIR str Deliverable output file folder (directory) 0 - 256  
FTYPE str Output file type 0 - 4 PIX | TIF
Default: PIX
FOPTIONS str Options for output file 0 - 64  
OUTBGD List[float] Output background value 0 - 1 Default: 0
EDGECLIP List[int] Automatic edge clipping (%) 0 - 1 0 - 49
Default: 0
MAPUNITS str Output projection units 0 - 256
BXPXSZ * str Horizontal output-pixel size 1 - 32  
BYPXSZ str Vertical pixel size 0 - 32  
TIPOSTRN str Tile positioning transformation 0 -    
FILEDEM str File or folder (directory) containing the digital elevation model 0 -    
DBEC List[int] Input elevation channel 0 - 1  
BACKELEV List[float] Background elevation value 0 - 1  
ELEVREF str Vertical reference for elevation values 0 -   MSL | ELLIPS | MATHMODEL
ELEVUNIT str Elevation value units 0 - 7 METER | FEET | US_FEET
ELFACTOR List[float] Elevation offset and scale 0 - 2  
FILEDBM str File containing the digital building models 0 -    
DBMPXERR List[int] Building model error 0 - 1 0 -
Default: 1
DBVS List[int] Input-vector layer 0 - 1  
ZREF str Vertical reference for DBM Z values 0 -   MSL | ELLIPS | MATHMODEL
Default: MSL
ZUNIT str DBM elevation value units 0 - 7 METER | FEET | US_FEET
Default: METER
ZFACTOR List[float] DBM elevation offset and scale 0 - 2 Default: 0.0,1.0
RESAMPLE str Resampling method 0 -   Default: CUBIC
ALGO str Processing algorithm 0 -   See Parameter Details.
Default: OCCLUDE
PROC str Processing unit configuration 0 -  

* Required parameter
Back to top

Parameter descriptions

MFILE

The name of an image file, a folder (directory), or a text file that contains the input images to process. If necessary, you can use a wildcard (*) with the parameter value.

If you are specifying an MFILE, you can use any of the following:
If you specify a text file, the following general rules apply:
Each MFILE line contains up to nine file-specific parameters in the following format, and in the order shown:
[FILI];[DBIC];[MMSEG];[DBIW];[SRCBGD];[EDGECLIP];[RADIODIF];[DBMPXERR];[ROLE]
              
Of the preceding, FILI is mandatory; the other parameters are optional. If not specified, the corresponding parameter value of the algorithm is used.
  1. [FILI]: input-file name
  2. [DBIC]: comma-delimited list of channels to process
  3. [MMSEG]: math-model-segment number
  4. [DBIW]: input window to process
  5. [SRCBGD]: rule identify background pixels
  6. [EDGECLIP]: percentage to clip from computed file extents
  7. [RADIODIF]: allowable radiometric difference for candidate images
  8. [DBMPXERR]: amount to grow voids before occlusion compensation
  9. [ROLE]: raster role
The following is an example of two lines of the MFILE:
"d:\ortho\src\32A.pix";1,-3;;;"FILE,ALL,0";;"ANY";4;
"d:\ortho\src\52A.pix";1,-3;2;500,500,10000,10000;"NONE";5;;;"PREP"
              

In the preceding example, channels 1 through 3 of file 32A.pix will be processed. Values for DBIW, MMSEG, and EDGECLIP will be used as defined at the algorithm level. SRCBGD is defined as "FILE,ALL,0". Before filling, the occluded regions will grow by four pixels, but no feathering will be applied.

For image 52A.pix, math-model segment 2 will be used. Channels 1 through 3 will be processed, and DBIW will be set to [500,500,10000,10000] for this image. The image is processed as if there is no source background, and the file extents computed automatically will be trimmed by five percent before generating the output file. Values for RADIODIF and DBMPXERR will be used as defined at the algorithm level. This scene will not be filled.

DBIC

The channel or channels to process in the input file.

Each channel must contain the same data type. If no value is specified for this parameter, all of the channels in the source file will be processed.

This parameter value can be overridden by a corresponding value in the MFILE text file.

MMSEG

The math-model segment of the input raw image to use in the orthorectification process. All math-model types are supported.

If this parameter is not specified, the last model segment of the input file is used.

This parameter can be overridden by a corresponding value in the MFILE text file.

DBIW

The raster window (Xoffset, Yoffset, Xsize, Ysize) of data to read from the input channels.

If no value is specified for this parameter, the entire image is processed. XOff, YOff define the upper-left starting pixel coordinates of the window. XSize is the number of pixels that define the window width. YSize is the number of lines that define the window height.

Note: This parameter is particularly useful when orthorectifying scanned-film airphotos, as it can be used to exclude the registration marks and ancillary data printed along the edge of the image.

SRCBGD

The pixels in the source image to be considered as background (NoData) pixels. Typically, if the resampling window for any ortho pixel contains a source background pixel, the ortho pixel is not processed and the output background value (OUTBGD) is written instead.

Available values for this parameter are:

With the ALL and ANY options, the background pixel is described by the "background rule" and a list of one or more pixel values for the different image channels. The "background rule" must be set to ALL or ANY. ALL indicates that the pixel value in all channels must match the provided background value for the pixel to be considered as background. ANY indicates that if any channel equals the background value, the pixel will be considered as background.

The background value is provided as either a single number (applied to all channels) or as a pixel "stack". If a pixel stack is provided, but the number of values does not equal the number of channels, the list will be truncated or the last value will be repeated, as necessary. The background values provided will be truncated to the range allowed by the source image data type.

The following examples apply to a three-channel, 8-bit unsigned image:

RADIODIF

The allowable extent of radiometric difference between a candidate image and the current image for it to be considered for occlusion recovery.

The following values are supported:

This parameter can be overridden by an entry in the MFILE.

OUTDIR

A folder (directory) to which the orthorectified images will be written. If the folder does not exist, it is created automatically.

The name of a generated orthorectified image file has generally the same base name as that of the source image file, but is prefixed by "to" to indicate it is orthorectified. If multiple source image files have the same base name, a new base name may be generated automatically for the scene.

If no value is specified for this parameter, a subfolder delivery is created automatically in the parent folder of the MFILE.

FTYPE

The format of the output file to create: .tif, .pix, or another GDB-supported file type.

Supported file formats include, among others:

For a complete list of GDB-recognized file types, see About Generic Database file formats

This parameter is optional.

FOPTIONS

The options to apply when creating the output file specific to the file format, such as compression schemes, file-format subtypes, and so forth. If most cases, the default option will suffice.

For a complete list of GDB-recognized file types, including the options available for each, see About Generic Database file formats

OUTBGD

The background (NoData) value to use for ortho pixels that are not populated. Each channel is set to the same background value. The background value provided is truncated to the range allowed by the source image data type.

EDGECLIP

The percentage of the image that is clipped from the edges during orthorectification. Clipping is applied to each edge of the image; for example, if the value specified is 5, five percent is clipped from the left-most edge and five percent from the right-most edge). The maximum value is 49 (percent).

Edge clipping is performed after the ortho image extents (ULX, ULY, LRX, LRY) are determined, but before the tile-positioning transformation (TIPOSTRN) is applied.

Note: This parameter is particularly useful for images in a north-south or east-west orientation, as it can be used to clip the undulating boundary that arises due to relief displacement.

MAPUNITS

The projection string for the output ortho image. If no value is specified for this parameter, the map units are determined automatically.

The standard definitions are as follows:

If METER or FEET is specified, the math model and DEM must be METER or FEET.

If a regular, Earth-referenced projection is specified, the math model and digital elevation model (DEM) must also use a regular projection (not necessarily the same one); neither METER nor FEET are allowed.

The label of a user-defined projection can also be specified if it exists in the file userproj.txt. Otherwise, the projection-parameter information must be provided as a string separated by a vertical bar (|). The projection-parameter string defines 18 parameters delimited by spaces, including Dearth, RefLong, RefLat, StdParallel1, StdParallel2, FalseEasting, FalseNorthing, Scale, Height, Long1, Lat1, Long2, Lat2, Azimuth, LandsatNum, LandsatPath and UnitsCode. For example, the projection "France93" can be specified as
LCC D350 | 0 0 3.0 46.5 44.0 49.0 700000 6600000 0 0 0 0 0 0 0 0 0 -1

This parameter can specify the UTM grid-zone number and row, and Earth model, as follows:

UTM [mm] [r] [Ennn]
where:

The Earth model can be specified for LONG/LAT (and other units except METER or FEET), as follows:

LONG/LAT [Ennn]

This parameter can specify the SPCS zone number and Earth model as follows:

SPCS [mmmm] [Ennn]

where [mmmm] is the four-digit zone number.

If the Earth model is not specified, it is assumed to be E000 (Clarke 1866).

If MAPUNITS is not specified, the logic for determining a default ortho-coordinate system is as follows:

BXPXSZ

The horizontal pixel size of the output image.

The output-pixel size is expressed in the units of the ortho coordinate system.

BYPXSZ

The vertical pixel size of the output image.

The output-pixel size is expressed in the units of the ortho coordinate system.

If no value is specified for this parameter, the value specified for the horizontal pixel size (BXPXSZ) is used.

TIPOSTRN

An upper-left corner-coordinate adjustment for the orthorectified image.

This parameter allows you to generate ortho images that occur in a specific raster grid. You specify it by providing a keyword and either two or four values.

The keyword indicates the relative positioning of the values:
After the keyword is specified, the values are:

These values define the position of the corner or center relative to the specified raster grid.

Of the four values, only Stride_X is required. If not specified, Stride_Y defaults to the Stride_X value, and Ref_X, Ref_Y default to 0.

Stride_X must double an integer multiplier of the horizontal pixel size, and Stride_Y must double an interger multiplier of the vertical pixel size.

For example:

TIPOSTRN="CORNER, 20, 20, 432345.000, 5438882.000"
          

In the preceding example, the upper-left corner of the upper-left pixel of the image will be an even 20-unit multiple from the reference point (432345.000, 5438882.000). Depending on the distance of the tile from that point, its upper-left x-coordinate can be 432345.000, 432365.000, or any other multiple, but will never be 432346.000 nor 432355.000.

If a value is specified for this parameter, it is applied in all scenarios, whether the image-corner coordinates come from the input file (MFILE), ULX and ULY, or through automatic computation.

This parameter is optional.

FILEDEM

The name of a file, folder (directory), or DEM-index file that contains DEM tiles.

If the value of FILEDEM is the name of a single-raster DEM file, the parameters DBEC, BACKELEV, ELEVREF, ELEVUNIT and ELFACTOR are used, if provided.

If no value is specified for FILEDEM, the offset component of ELFACTOR and the ELEVREF parameter are used to define the height surface for orthorectification.

Note: If ELEVREF is Mean Sea Level (MSL), this constant elevation is treated as an MSL height and may be converted to an ellipsoidal height before use.

If the value of FILEDEM is the name of an existing folder (directory), the specified folder is searched for the file index.txt. This file must be in the DEM-index format, as described in Details, later in this topic.

This parameter is optional.

DBEC

Specifies the channel number for the input digital elevation model (DEM) elevation channel to be processed.

This parameter is ignored if the value of FILEDEM is an empty string or a DEM-index text file.

If the value of FILEDEM is a single file, and you do not specify a value for DBEC, a channel is selected as the most likely DEM channel by using the following logic:

BACKELEV

The background elevation (NoData) value in the input elevation channel.

Output ortho pixels with this value are set to the value of OUTBGD (Output Background), as it is impossible to interpolate a height for these pixels.

If no value is specified for this parameter, the function checks for ELEVATION_BACKGROUND or NO_DATA_VALUE metadata tags, first at the channel level, and then at the file level. If this value is not specified or found in the metadata, the function uses the default value of -32768.

This parameter is ignored if the value of FILEDEM is an empty string or a DEM-index text file.

This parameter is optional.

ELEVREF

The vertical reference for the elevation values contained in the source digital elevation model (DEM), or for the constant value of ELFACTOR, if it is used.

Acceptable values are:

This parameter is ignored if FILEDEM is an empty string or a DEM index text file.

ELEVUNIT

The units of the elevation values that are stored as pixel values in the input digital elevation model (DEM), as specified either by FILEDEM or by the first entry in ELFACTOR.

Acceptable values are:

This parameter is ignored if the value of FILEDEM is an empty string or a DEM-index text file.

Note: If elevation values are specified as FEET, the conversion factor to meters is 0.3048 (corresponding to International Feet); if US_FEET is specified, the conversion factor is 1200/3937 (corresponding to U.S. Survey Feet).

ELFACTOR

If an input digital elevation model (DEM) is specified and will be used in the orthorectification (see FILEDEM), the value of this parameter is used to shift and scale the DEM pixel values to values in the units indicated by the value of ELEVUNIT (Elevation Unit).

Using this parameter, two values are specified: the first defines the offset, and the second, optionally, specifies the scale.

The conversion formula is as follows:

elevation_value = scale * (DEM_pixel_value + offset)
          

If no value is specified for FILEDEM, only the offset value of ELFACTOR is significant. This value is interpreted as a uniform elevation value in the units specified for ELEVUNIT and using the vertical reference specified for ELEVREF.

If no value is specified for ELFACTOR, an offset of 0.0 is applied by default, and the scale default is 1.0.

This parameter is ignored if the value of FILEDEM is an empty string or a DEM index text file.

FILEDBM

The name of a file containing triangulated building models.

If the value of FILEDBM is the name of a single-vector file, the parameters DBVS, DBMELEVREF, DBMELEVUNIT and DBMELFACTOR are used, if provided.

If no value is specified for FILEDBM, the parameters DBVS, DBMELEVREF, DBMELEVUNIT and DBMELFACTOR are ignored.

This parameter is optional.

DBMPXERR

The accuracy of the building models in units of ortho pixels.

This parameter is used to grow the occluded regions before they are filled in with data from neighboring images. This allows the algorithm to compensate for small inaccuracies in the elevation data set.

DBVS

The segment number for the input digital building model (DBM) vector layer to be processed. The specified vector layer must contain three-dimensional (3-D) triangles that represent building rooftops.

This parameter is not used if the value of FILEDBM is an empty string.

If a single file is specified as the value of FILEDBM, and no value is specified for DBVS, the first vector segment of the FILEDBM value is used.

ZREF

The vertical reference for the elevation values contained in the source digital building model (DBM), if used.

Acceptable values are:

ZUNIT

The units of the elevation values stored as vertex z-coordinates in the input digital building model (DBM), as specified by the value of FILEDBM.

Acceptable values are:

If elevation values are specified as FEET, the conversion factor to meters is 0.3048 (corresponding to International Feet); if specified as US_FEET, the conversion factor is 1200/3937 (corresponding to U.S. Survey Feet).

ZFACTOR

If an input digital building model (DBM) is specified and will be used in the orthorectification (see FILEDBM), the value of this parameter is used to shift and scale the vertex z-coordinates to values in the units indicated by the value of DBMELEVUNIT (Elevation Unit).

Using this parameter, two values are specified: the first defines the offset while the second, optionally, specifies the scale.

The conversion formula is as follows:

elevation_value = scale * (Vertex_Z_value + offset)
          

If no value is specified for FILEDBM, this value is ignored.

If no value is specified for ELFACTOR, the offset default is 0.0 and the scale default is 1.0.

RESAMPLE

The resampling method to use in the orthorectifying process.

The following methods are supported:

For each resampling method, the parameters MIN=[min], MAX=[max], and FILL=[NN or BGD] can be appended as a comma-delimited list. MIN and MAX define the clamp range for output pixels; this is useful when you want to keep pixel values within a certain range (for example, 1 to 2047 if 11-bit data is stored in a 16-bit file). FILL defines the behavior when the resampling window contains NoData pixels: NN directs the resampler to use the nearest-neighbor method, while BGD indicates that the output pixel will be set to the background value. By default, NN is used as the value of FILL.

ALGO

Specifies the algorithm. The following values are valid:

PROC

Controls the amount of memory (in megabytes) used by the algorithm.

If no host memory limit is specified, the function uses a default of 1 GB or half the available physical memory, whichever is smaller.

Back to top

Details

TORTHO provides GPU-accelerated full orthorectification of images using digital elevation models (DTMs) and digital building models (DBMs). The output ortho images are corrected for geometric distortions due to sensor tilt and ground-surface relief, are compensated at occluded areas, and are further post-processed to fill holes and reduce color differences along seam lines.

Back to top

Example

The sample code shows the true-orthorectification production of a set of images using both a DTM and a DBM.

from pci.tortho import tortho


mfile = r"F:/STI/Img/*.pix"
dbic = []
mmseg = []
dbiw = []
srcbgd = "ALL,0"
radiodif = ""
outdir = ""
ftype = "PIX"
foptions = ""
outbgd = [0]
edgeclip = [0]
mapunits = "France93    D350"
bxpxsz = "0.1"
bypxsz = "0.1"
tipostrn = "CORNER,16,16,0,0"
filedem = r"F:/STI/DEM/dtm_10cm.jp2"
dbec = [1]
backelev = [-32768.0]
elevref = "MATHMODEL"
elevunit = "METER"
elfactor = [0.0,1.0]
filedbm = r"F:/STI/DEM/dbm_tin.pix"
dbmpxerr = [4]
dbvs = [2]
zref = "MATHMODEL"
zunit = "METER"
zfactor = [0.0,1.0]
resample = "CUBIC"
algo = ""
proc = "600"

tortho(mfile, dbic, mmseg, dbiw, srcbgd, radiodif, outdir, ftype, foptions, outbgd, edgeclip, mapunits, bxpxsz, bypxsz, tipostrn, filedem, dbec, backelev, elevref, elevunit, elfactor, filedbm, dbmpxerr, dbvs, zref, zunit, zfactor, resample, proc)
        

© PCI Geomatics Enterprises, Inc.®, 2026. All rights reserved.