mapproject is used to orthorectify (map-project) a camera
image onto a DEM or datum. (ASP is able to use map-projected images to
run stereo, see Section 6.1.7.)
mapproject program can be run using multiple processes and can
be distributed over multiple machines. This is particularly useful for
ISIS cameras, as in that case any single process must use only one
thread due to the limitations of ISIS. The tool splits the image up
into tiles, distributes the tiles to sub-processes, and then merges
the tiles into the requested output image. If the input image is small
but takes a while to process, smaller tiles can be used to
start more simultaneous processes (use the parameters
It is important to note that processing more tiles at a time may actually slow things down, if all processes write to the same disk and if processing each tile is dominated by the speed of writing to disk. Hence some benchmarking may be necessary for your camera type and storage setup.
The grid size, that is the dimension of pixels on the ground, set via
--tr option, should be in units as expected by the projection
string obtained either from the DEM to project onto, or, if specified,
--t_srs option. If the grid size is not set, it will be
estimated as the mean ground sampling distance (GSD). See the
--tr option for how this affects the extent of the output image.
Mapproject assuming the
longlat projection and setting the grid
size in degrees:
mapproject --tr 0.0001 DEM.tif image.tif camera.tsai output.tif
Map-project a .cub file (it has both image and camera information) for the Moon. Use a custom stereographic projection:
proj="+proj=stere +lat_0=-85.3643 +lon_0=31.2387 +R=1737400 +units=m +no_defs"
The grid size is set to 1 meter/pixel:
mapproject --tr 1.0 --t_srs "$proj" DEM.tif image.cub output.tif
Map-project an image file with associated .xml camera file. Use bundle-adjusted cameras (Section 16.5):
mapproject -t rpc --bundle-adjust-prefix ba/run \ DEM.tif image.tif image.xml output.tif
Mapproject using the CSM camera model (Section 8.12):
mapproject DEM.tif image.cub camera.json output.tif
Mapproject onto a datum rather than a DEM:
mapproject WGS84 image.tif image.xml output.tif
Valid datum names include WGS84, NAD83, NAD27, D_MOON, D_MARS, and MOLA.
If processing DigitalGlobe images, both the rigorous DG model
-t dg) and its RPC approximation (
-t rpc) from the XML metadata
file can be used for map projection. In practice, the latter is
recommended for most applications. The former is slightly more accurate,
but much slower.
If desired to change the range of longitudes from [0, 360] to [-180,
180], or vice-versa, post-process obtained mapprojected image with
image_calc (Section 16.31).
16.38.2. Saved metadata¶
The output image will have the following metadata saved to its geoheader:
INPUT_IMAGE_FILE, the input image name.
BUNDLE_ADJUST_PREFIX, the bundle adjustment prefix. Set to
NONEif not present.
CAMERA_MODEL_TYPE, this is the session name, such as set with
CAMERA_FILE, the camera file used on input. Can be empty if the camera is contained within the input image.
DEM_FILE, the DEM used in mapprojection.
In addition, if the cameras have been bundle-adjusted, the translation and
quaternion rotation from the .adjust file will be saved to the fields
ADJUSTMENT_QUATERNION. This is useful for
having mapprojection be reproducible if the separately stored
are not available.
mapproject [options] <dem> <camera-image> <camera-model> <output-image>
16.38.4. Command-line options¶
- --nodata-value <float(default: -32768)>
No-data value to use unless specified in the input image.
- --t_srs <proj4 string>
Specify the output projection (PROJ.4 string). If not provided, use the one from the DEM.
- --tr <float>
Set the output file resolution (ground sample distance) in target georeferenced units per pixel. This may be in degrees or meters, depending on your projection. The center of each output pixel will be at integer multiples of this grid size (hence the output image will extend for an additional half a pixel at each edge).
- --mpp <float>
Set the output file resolution in meters per pixel.
- --ppd <float>
Set the output file resolution in pixels per degree.
- --datum-offset <float>
When projecting to a datum instead of a DEM, add this elevation offset to the datum.
- -t, --session-type <pinhole|isis|rpc>
Select the stereo session type to use for processing. Choose
rpcif it is desired to later do stereo with the
- --t_projwin <xmin ymin xmax ymax>
Limit the map-projected image to this region, with the corners given in georeferenced coordinates (xmin ymin xmax ymax). Max is exclusive.
- --t_pixelwin <xmin ymin xmax ymax>
Limit the map-projected image to this region, with the corners given in pixels (xmin ymin xmax ymax). Max is exclusive.
- --bundle-adjust-prefix <name>
Use the camera adjustment obtained by previously running bundle_adjust with this output prefix.
- --ot <type (default: Float32)>
Output data type, when the input is single channel. Supported types: Byte, UInt16, Int16, UInt32, Int32, Float32. If the output type is a kind of integer, values are rounded and then clamped to the limits of that type. This option will be ignored for multi-channel images, when the output type is set to be the same as the input type.
Use nearest neighbor interpolation instead of bicubic interpolation.
- --mo <string>
Write metadata to the output file. Provide as a string in quotes if more than one item, separated by a space, such as
VAR1=VALUE1 VAR2=VALUE2. Neither the variable names nor the values should contain spaces.
- --processes <integer>
Number of processes to use on each node (the default is for the program to choose).
- --num-processes <integer>
Same as –processes. Used for backwards compatibility.
List of available computing nodes to use. If not set, use the local machine. See also Section 8.16.
Size of square tiles to break up processing into. Each tile is run by an individual process. The default is 1024 pixels for ISIS cameras, as then each process is single-threaded, and 5120 pixels for other cameras, as such a process is multi-threaded, and disk I/O becomes a bigger consideration.
Turn on velocity aberration correction for Optical Bar and non-ISIS linescan cameras (Section 11.4.2). This option impairs the convergence of bundle adjustment.
Turn on atmospheric refraction correction for Optical Bar and non-ISIS linescan cameras. This option impairs the convergence of bundle adjustment.
Display the computed projection information and estimated ground sample distance (pixel size on the ground), and quit.
Do not write information in the geoheader. Otherwise mapproject will write the camera model type, the bundle adjustment prefix used, the rotation and translation from the .adjust file, the DEM it mapprojected onto, and the value of the
Suppress output from sub-processes.
- --threads <integer (default: 0)>
Select the number of threads to use for each process. If 0, use the value in ~/.vwrc.
- --cache-size-mb <integer (default = 1024)>
Set the system cache size, in MB, for each process.
Use the CSM model with DigitalGlobe linescan cameras (
-t dg). No corrections are done for velocity aberration or atmospheric refraction.
Use the CSM model with ASTER cameras (
Tell GDAL to not create bigtiffs.
- --tif-compress <None|LZW|Deflate|Packbits>
TIFF compression method.
- -v, --version
Display the version of software.
- -h, --help
Display the help message.