worldfileread

Read world file and return reference object

Syntaxes of the worldfileread function that return referencing matrices will be removed in a future release. Use a syntax that returns a reference object instead. For more information, see Compatibility Considerations.

Syntax

R = worldfileread(worldFileName,coordinateSystemType,rasterSize)

Description

R = worldfileread(worldFileName,coordinateSystemType,rasterSize) reads the world file, worldFileName, and constructs a spatial referencing object, R. The argument coordinateSystemType specifies the type of referencing object. rasterSize specifies the size of the image corresponding to the world file.

Examples

Read Image Referenced to Projected Coordinate System

Read an ortho image referenced to a projected coordinate system (Massachusetts State Plane Mainland).

filename = 'concord_ortho_w.tif';
[X, cmap] = imread(filename);

Derive world file name from image file name.

worldFileName = getworldfilename(filename);

Read the world file, returning a referencing object.

R = worldfileread(worldFileName, 'planar', size(X))

R = 
  MapCellsReference with properties:

            XWorldLimits: [207000 209000]
            YWorldLimits: [911000 913000]
              RasterSize: [2000 2000]
    RasterInterpretation: 'cells'
        ColumnsStartFrom: 'north'
           RowsStartFrom: 'west'
      CellExtentInWorldX: 1
      CellExtentInWorldY: 1
    RasterExtentInWorldX: 2000
    RasterExtentInWorldY: 2000
        XIntrinsicLimits: [0.5 2000.5]
        YIntrinsicLimits: [0.5 2000.5]
      TransformationType: 'rectilinear'
    CoordinateSystemType: 'planar'
            ProjectedCRS: []

Read Image Referenced to Geographic Coordinate System

Read image reference to a geographic coordinate system.

filename = 'boston_ovr.jpg';
RGB = imread(filename);

Derive world file name from image file name,

worldFileName = getworldfilename(filename);

Read world file, returning a referencing object.

R = worldfileread(worldFileName, 'geographic', size(RGB))

R = 
  GeographicCellsReference with properties:

             LatitudeLimits: [42.3052018188767 42.4165064733949]
            LongitudeLimits: [-71.1308390797572 -70.9898400731705]
                 RasterSize: [769 722]
       RasterInterpretation: 'cells'
           ColumnsStartFrom: 'north'
              RowsStartFrom: 'west'
       CellExtentInLatitude: 0.000144739472715501
      CellExtentInLongitude: 0.000195289482807142
     RasterExtentInLatitude: 0.11130465451822
    RasterExtentInLongitude: 0.140999006586757
           XIntrinsicLimits: [0.5 722.5]
           YIntrinsicLimits: [0.5 769.5]
       CoordinateSystemType: 'geographic'
              GeographicCRS: []
                  AngleUnit: 'degree'

Input Arguments

worldFileName — Name of world file

character vector

Name of world file, specified as a character vector.

Example: worldFileName = getworldfilename(filename);

Data Types: char

coordinateSystemType — Type of referencing object

'planar' | 'geographic'

Type of referencing object, specified as one of the following:

Value	Description
'geographic'	Latitude-longitude systems
'planar'	Projected map coordinate systems

Example: R = worldfileread(worldFileName, 'geographic', size(RGB));

Data Types: char

rasterSize — Size of the image corresponding to the world file

two-element vector

Size of the image corresponding to the world file, specified as a two-element vector, [m n], where m is the number of rows in the image and n is the number of columns in the image.

Example: size(I)

Data Types: double

Output Arguments

R — Spatial referencing object

raster reference object

Spatial referencing object, returned as a raster reference object.

Version History

Introduced before R2006a

R2022a: Syntaxes that return referencing matrices warn

Syntaxes of the worldfileread function that return referencing matrices issue a warning that they will be removed in a future release. Use syntaxes that return reference objects 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 limits, and the direction of its rows and columns. For more information about reference object properties, see the GeographicCellsReference and MapPostingsReference objects.

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

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

• Most functions that accept referencing matrices as inputs also accept reference objects.

To update your code, specify the coordinate system type as a second argument. Use 'planar' for planar map coordinates or 'geographic' for geographic coordinates. Specify the size of the associated raster, A, as a third argument.

Will Be Removed	Recommended
refmat = worldfileread(worldFileName);	R = worldfileread(worldFileName, ... coordinateSystemType,size(A));

R2020b: Syntaxes that return referencing matrices will be removed

Syntaxes of the worldfileread function that return referencing matrices will be removed in a future release.