mapoutline

Compute outline of georeferenced image or data grid

Syntax

[x,y] = mapoutline(R,height,width)
[x,y] = mapoutline(R, sizea)
[x,y] = mapoutline(...,'close')
[lon,lat] = mapoutline(R,...)
outline = mapoutline(...)


Description

[x,y] = mapoutline(R,height,width) computes the outline of a georeferenced image or regular gridded data set in map coordinates. R is a MapCellsReference or MapPostingsReference object. height and width are the image dimensions. x and y are 4-by-1 column vectors containing the map coordinates of the outer corners of the corner pixels, in the following order:

(1,1), (height,1), (height, width), (1, width).

[x,y] = mapoutline(R, sizea) accepts sizea = [height, width, ...] instead of height and width.

[x,y] = mapoutline(...,'close') returns x and y as 5-by-1 vectors, appending the coordinates of the first of the four corners to the end.

[lon,lat] = mapoutline(R,...), where R georeferences pixels to longitude and latitude rather than map coordinates, returns the outline in geographic coordinates. Longitude must precede latitude in the output argument list.

outline = mapoutline(...) returns the corner coordinates in a 4-by-2 or 5-by-2 array.

Examples

Draw a red outline delineating the Boston GeoTIFF image, which is referenced to the Massachusetts Mainland State Plane coordinate system with units of survey feet.

figure
info = georasterinfo('boston.tif');
R = info.RasterReference;
[x,y] = mapoutline(R,R.RasterSize,'close');

hold on
plot(x,y,'r')
xlabel('MA Mainland State Plane easting, survey feet')
ylabel('MA Mainland State Plane northing, survey feet')

Draw a black outline delineating a TIFF image of Concord, Massachusetts, while lies roughly 25 km north west of Boston. Convert world file units to survey feet from meters to be consistent with the Boston image.

info  = imfinfo('concord_ortho_w.tif');
R = worldfileread('concord_ortho_w.tfw','planar', ...
        [info.Height info.Width]);
[x,y] = mapoutline(R, info.Height, info.Width, 'close');
x = x * unitsratio('sf','meter');
y = y * unitsratio('sf','meter');
plot(x,y,'k')

Version History

Introduced before R2006a

R2024b: mapoutline does not accept referencing matrices as input

The mapoutline does not accept referencing matrices as input. Use a map raster reference object (specified as a MapCellsReference or MapPostingsReference object) or a geographic raster reference object (specified as a GeographicCellsReference or GeographicPostingsReference object) as input instead. Reference objects have several advantages over referencing matrices.

• Unlike referencing matrices, reference objects have properties that document the size of the associated raster, its world limits, and the direction of its rows and columns.

• You can manipulate the limits of rasters associated with reference objects using the mapcrop function.

• You can manipulate the size and resolution of rasters associated with reference objects using the mapresize function.

The strategy you use to update your code depends on whether your data is in planar or geographic coordinates.

Planar Map Coordinates

If the referencing matrix is in planar map coordinates, create a map reference object and use a different syntax of the mapoutline function.

• Create a map reference object for a raster of cells by using the maprefcells function.

• Create a map reference object for a raster of regularly posted samples by using the maprefpostings function.

• Alternatively, you can convert from a referencing matrix to a map reference object by using the refmatToMapRasterReference function.

Once you have created a reference object, replace uses of the mapoutline function in your code with the syntax [X,Y] = mapoutline(R,R.RasterSize), where R is the reference object.

Geographic Coordinates

If the referencing matrix is in geographic coordinates, create a geographic reference object and replace uses of the mapoutline function with the outlinegeoquad function.

• Create a geographic reference object for a raster of cells by using the georefcells function.

• Create a geographic reference object for a raster of regularly posted samples by using the georefpostings function.

• Convert from a referencing matrix to a geographic reference object by using the refmatToGeoRasterReference function.

Once you have created a reference object, replace uses of the mapoutline function in your code with the outlinegeoquad syntax [LAT,LON] = outlinegeoquad(R.LatitudeLimits,R.LongitudeLimits), where R is the reference object.

R2024b: mapoutline does not accept structure arrays as input

The mapoutline function does not accept structure arrays as input, including structure arrays containing RefMatrix, Height, and Width fields. Use a map raster reference object as input instead.

To update your code, convert the structure array to a reference object by using the refmatToMapRasterReference function. Then, replace uses of the mapoutline function with the syntax [X,Y] = mapoutline(R,R.RasterSize), where R is the reference object.

To Be Removed	Recommended
[X,Y] = mapoutline(INFO);	R = refmatToMapRasterReference(INFO.RefMatrix, ... [INFO.Height INFO.Width]); [X,Y] = mapoutline(R,R.RasterSize);

R2023b: mapoutline will not accept referencing matrices or structure arrays as input

When you specify a referencing matrix or a structure array containing RefMatrix, Height, and Width fields as input, the mapoutline function issues a warning that it will not accept referencing matrices as input in a future release.