Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

ISIS Documentation

maptrim

Trim edges of a map projected image

This program trims map projected images and sets valid pixels that fall outside a specified bounding box to NULL. By default, the pixels that fall outside the minimum and maximum latitude and longitude found within the Mapping Group of the input cube's label are set to NULL.

The values entered for minimum and maximum latitude and longitude must be in the same longitude domain, longitude direction, and latitude type as the settings in the input image labels within the Mapping Group. If the values entered are in a different longitude domain, they will be interpreted as the domain setting in the image labels, and the entire output cube could contain only NULL pixels. For example, if the input cube's Mapping Group has a longitude direction of positive east and the user specifies values in west longitude, the longitude direction will be interpreted as positive east.

Selectable Modes to Trim an Image
Option Result
Trim The image is resized. The pixel dimensions of the file are retained; therefore, the number of pixels is the same. The pixels that fall outside the default or specified latitude and longitude range are set to NULL.
Crop The image is resampled and trimmed to the exact latitude and longitude range specified for the bounding box. The pixels that fall outside the specified range are not set to NULL.
Both The image is resampled and trimmed to the exact latitude and longitude range specified for the bounding box. The pixels that fall outside the bounding box are set to NULL.

Warnings:

Mapping information updated after image is cropped:
When the "crop" or "both" option is used, the keywords MinimumLatitude, MaximumLatitude, MinimumLongitude, and MaximumLongitude are removed from the labels. The values that the uncropped image contains have become inaccurate to use for the cropped image because after an image has been cropped, the UpperLeftCornerX and UpperLeftCornerY keywords, where these values begin, have been updated in the labels. Once the labels are updated, and if displayed with an image viewer, such as qview, the latitude and longitude values can be reported accurately.

Mosaicking cropped images:
The cropped images can be mosaicked into an existing output mosaic file using mapmos, or can be included in the input file list for automos. If automos is used, the "grange=user" parameter may have to be entered along with the latitude and longitude range of the mosaic depending on the ISIS version. The option to automatically determine the minimum and maximum latitude and longitude range from the input list in automos may be used but the Mapping Group will only have the UpperLeftCornerX and UpperLeftCornerY keywords.

Note: This application does not handle non-projected images (i.e. images that are not Level2 or a mosaic). To trim a Level1 image, please refer to camtrim.

Categories

Related Applications to Previous Versions of ISIS

This program replaces the following application existing in previous versions of ISIS:
  • trimsinu

Related Objects and Documents

Applications

History

Tracie Sucharski2003-02-28 Original version
Tracie Sucharski2003-04-03 Changed brief description, added error check for no values entered for slat,elat,slon,elon.
Stuart Sides2003-05-16 Modified schema location from astrogeology... to isis.astrogeology..."
Stuart Sides2003-07-29 Modified filename parameters to be cube parameters where necessary
Brendan George2005-11-21 Added application test
Sean Crosby2007-03-16 Added cropping and crop+trim ability; modified apptest
Christopher Austin2009-01-27 Fixed parameter names
Travis Addair2009-08-10 Mapping group parameters are now placed into the print file.
Mackenzie Boyd2009-08-12 Modified call to crop to handle from and to parameters with spaces in directories.
Jai Rideout2011-01-11 Updated documentation and testing with Ella Lee in preparation for the 3.4.0 release. Fixed various inconsistencies in the documentation and rewrote some parts to make it clearer. Added an example. Added two new tests to test getting the lat/lon range from the cube labels and the processing of level 1 images.
Debbie A. Cook2012-12-06 Changed to use TProjection instead of Projection. References #775
Kimberly Oyama2013-01-14 Changed the temporary file name to be unique between executions so there are no conflicts when multiple instances of the program are running. Added an app test to exercise this change. Fixes #1216.
Ella Mae Lee2013-11-13 Updated the documentation to clarify the results of the different trim options and added new example , fixes #1621.

Parameters

Files

Use this parameter to specify the input filename. The selected option will be applied to all the bands in the file by default, or the selected bands.
Type cube
File Mode input
Filter *.cub

This output file will contain the results of the selected MODE option.
Type cube
File Mode output
Filter *.cub

Trim options

This parameter allows the user to select a trim option. By default, all pixels outside the default or specified latitude and longitude range are set to NULL. To override the default, select CROP or BOTH.
Type string
Default TRIM
Option List:
Option Brief Description
TRIMSet all pixels outside the bounding box to NULL The original dimensions of the map are preserved while all pixels outside the default or specified latitude and longitude range are set to NULL.
CROPCrop the image to the exact latitude and longitude range The dimensions of the output file are cropped to the exact latitude and longitude range specified by the user. No pixels are set to NULL.
BOTHCrop the image and set all pixels outside the bounding box to NULL The dimensions of the output file are cropped to the exact latitude and longitude range specified by the user, and all pixels outside the bounding box are set to NULL.

Trim Parameters

Specify the starting latitude of range to exclude from processing. Any pixel whose latitude is less than this value will be set to NULL and/or trimmed.
Type double
Internal Default Minimum latitude in labels
Minimum -90 (inclusive)
Maximum 90 (inclusive)
Less Than MAXLAT

Specify the ending latitude of range to exclude from processing. Any pixel whose latitude is greater than this value will be set to NULL and/or trimmed.
Type double
Internal Default Maximum latitude in labels
Minimum -90 (inclusive)
Maximum 90 (inclusive)
Greater Than MINLAT

Specify the starting longitude of range to exclude from processing. Any pixel whose longitude is less than this value will be set to NULL and/or trimmed.
Type double
Internal Default Minimum longitude in labels
Minimum -360 (inclusive)
Maximum 360 (inclusive)
Less Than MAXLON

Specify the ending longitude of range to exclude from processing. Any pixels whose longitude is greater than this value will be set to NULL and/or trimmed.
Type double
Internal Default Maximum longitude in labels
Minimum -360 (inclusive)
Maximum 360 (inclusive)
Greater Than MINLON

Example 1

Trim a projected image

This example illustrates how to trim a cube that is projected to a sinusoidal projection. All pixels that have latitudes less than 15° or greater than 20° and longitudes less than 222° or greater than 230° are set to NULL. The TRIM option is used since no option is selected.

Command Line

Command to run maptrim in the command line mode to set all pixels outside the specified bounding box to NULL.
maptrim FROM=input.cub TO=trimmed.cub MINLAT=15 MAXLAT=20 MINLON=222 MAXLON=230

Input Image

input.cub

Input cube

input.cub

Parameter Name: FROM

This is the input cube to trim.

Output Image

trimmed.cub

Output cube

trimmed.cub

Parameter Name: TO

This is the trimmed cube. Notice that all pixels that fell outside the user-specified range were set to NULL.

Example 2

Trim a projected image using CROP and BOTH options

This example illustrates how to trim a cube that is projected to a sinusoidal projection. The first part will crop the image to a specified bounding box, and the second part will set pixels outside the bounding box to NULL.

Command Line

Command to run maptrim in the command line mode to extract the specified bounding box from the input cube.
maptrim FROM=LMMP_SAB_sinu.cub to=sinu_crop.cub mode=crop minlat=-60.5836 maxlat=-60.3129 minlon=-161.07 maxlon=-160.377

Input Image

input.cub

Input cube

input.cub

Parameter Name: FROM

This is the input cube to trim.

Output Images

sinu_crop.cub

Output cube

sinu_crop.cub

Parameter Name: TO

This is the cropped cube. Notice that only the specified bounding box was extracted out of the input cube.

sinu_both.cub

Output cube

sinu_both.cub

Parameter Name: TO

The image cube shown above was cropped and trimmed to create the image cube shown on the left. Notice that all the pixels outside the specified latitude and longitude range have been set to NULL in this example.

The following command line was used to create this output cube:

maptrim from=LMMP_SAB_sinu.cub to=sinu_both.cub mode=both minlat=-60.5836 maxlat=-60.3129 minlon=-161.07 maxlon=-160.377