An object representing a spatial extent. It encapsulates a Coordinate Reference System id (CRS) and coordinates.

It leverages proj4js to do the heavy-lifting of defining and transforming coordinates between reference systems. As a consequence, every EPSG code known by proj4js can be used out of the box, as such:

// an extent defined by bottom-left longitude 0 and latitude 0 and top-right longitude 1 and
// latitude 1
const extent = new Extent('EPSG:4326', 0, 0, 1, 1);

For other EPSG codes, you must register them with Instance.registerCRS() :

    Instance.registerCRS('EPSG:3946',
'+proj=lcc +lat_1=45.25 +lat_2=46.75 +lat_0=46 +lon_0=3 +x_0=1700000 +y_0=5200000 + \
ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs');

extent = new Extent(
'EPSG:3946',
1837816.94334, 1847692.32501,
5170036.4587, 5178412.82698);

Constructors

  • Constructs an Extent object.

    Parameters

    • crs: string

      The CRS code the coordinates are expressed in. Every EPSG code known by proj4js can be used directly. For others, you must manually register them. Please refer to proj4js doc for more information.

    • Rest ...values: ExtentParameters

      The extent values.

    Returns Extent

Accessors

Methods

  • Converts this extent into another CRS. If crs is the same as the current CRS, the original object is returned.

    Parameters

    • crs: string

      the new CRS

    Returns Extent

    the converted extent.

  • Sets target with the center of this extent.

    Parameters

    • Optional target: Vector2

      the vector to set with the center's coordinates. If none provided, a new one is created.

    Returns Vector2

    the modified object passed in argument.

  • Sets target with the center of this extent. Note: The z coordinate of the resulting vector will be set to zero.

    Parameters

    • Optional target: Vector3

      the vector to set with the center's coordinates. If none provided, a new one is created.

    Returns Vector3

    the modified object passed in argument.

  • Sets the target with the width and height of this extent. The x property will be set with the width, and the y property will be set with the height.

    Parameters

    • target: Vector2 = ...

      the optional target to set with the result.

    Returns Vector2

    the modified object passed in argument, or a new object if none was provided.

  • Returns true if the two extents are equal.

    Parameters

    • other: Extent

      The extent to compare.

    • epsilon: number = 0.00001

      The optional comparison epsilon.

    Returns boolean

    true if the extents are equal, otherwise false.

  • Expands the extent to contain the specified coordinates.

    Parameters

    Returns void

  • Returns an extent that is adjusted so that its edges land exactly at the border of the grid pixels. Optionally, you can specify the minimum pixel size of the resulting extent.

    Parameters

    • gridExtent: Extent

      The grid extent.

    • gridWidth: number

      The grid width, in pixels.

    • gridHeight: number

      The grid height, in pixels.

    • Optional minPixWidth: number

      The minimum width, in pixels, of the resulting extent.

    • Optional minPixHeight: number

      The minimum height, in pixels, of the resulting extent.

    Returns {
        extent: Extent;
        height: number;
        width: number;
    }

    The adjusted extent and pixel size of the adjusted extent.

    • extent: Extent
    • height: number
    • width: number
  • Set this extent to the intersection of itself and other

    Parameters

    • other: Extent

      the bounding box to intersect

    Returns this

    the modified extent

  • Returns true if this bounding box intersect with the bouding box parameter

    Parameters

    • bbox: Extent

      the bounding box to test

    Returns boolean

    true if this bounding box intersects with the provided bounding box

  • Tests whether this extent is contained in another extent.

    Parameters

    • other: Extent

      the other extent to test

    • epsilon: null | number = null

      the precision delta (+/- epsilon). If this value is not provided, a reasonable epsilon will be computed.

    Returns boolean

    true if this extent is contained in the other extent.

  • Checks whether the specified coordinate is inside this extent.

    Parameters

    • coord: Coordinates

      the coordinate to test

    • epsilon: number = 0

      the precision delta (+/- epsilon)

    Returns boolean

    true if the coordinate is inside the bounding box

  • Checks the validity of the extent.

    Returns boolean

    true if the extent is valid, false otherwise.

  • Returns the normalized offset from bottom-left in extent of this Coordinates

    Parameters

    • coordinate: Coordinates

      the coordinate

    • target: Vector2 = ...

      optional Vector2 target. If not present a new one will be created.

    Returns Vector2

    normalized offset in extent

    Example

    extent.offsetInExtent(extent.center())
    // returns `(0.5, 0.5)`.
  • Set the coordinate reference system and values of this extent.

    Parameters

    Returns this

    this object modified

  • Moves the extent by the provided x and y values.

    Parameters

    • x: number

      the horizontal shift

    • y: number

      the vertical shift

    Returns this

    the modified extent.

  • Subdivides this extents into x and y subdivisions.

    Notes:

    • Subdivisions must be strictly positive.
    • If both subvisions are 1, an array of one element is returned, containing a copy of this extent.

    Parameters

    • xSubdivs: number

      The number of subdivisions on the X/longitude axis.

    • ySubdivs: number

      The number of subdivisions on the Y/latitude axis.

    Returns Extent[]

    the resulting extents.

    Example

    const extent = new Extent('EPSG:3857', 0, 100, 0, 100);
    extent.split(2, 1);
    // [0, 50, 0, 50], [50, 100, 50, 100]
  • Returns a Box3 that matches this extent.

    Parameters

    • minHeight: number

      The min height of the box.

    • maxHeight: number

      The max height of the box.

    Returns Box3

    The box.

  • Divides this extent into a regular grid. The number of points in each direction is equal to the number of subdivisions + 1. The points are laid out row-wise, from west to east, and north to south:

    1 -- 2
    | |
    3 -- 4

    Type Parameters

    Parameters

    • xSubdivs: number

      The number of grid subdivisions in the x-axis.

    • ySubdivs: number

      The number of grid subdivisions in the y-axis.

    • target: T

      The array to fill.

    • stride: number

      The number of elements per item (2 for XY, 3 for XYZ).

    Returns T

    the target.

  • Returns an extent with a margin.

    Parameters

    • x: number

      The horizontal margin, in CRS units.

    • y: number

      The vertical margin, in CRS units.

    Returns Extent

    a new extent with a specified margin applied.

    Example

    const extent = new Extent('EPSG:3857', 0, 100, 0, 100);
    const margin = extent.withMargin(10, 15);
    // new Extent('EPSG:3857', -10, 110, -15, 115);
  • Returns an extent with a relative margin added.

    Parameters

    • marginRatio: number

      The margin, in normalized value ([0, 1]). A margin of 1 means 100% of the width or height of the extent.

    Returns Extent

    a new extent with a specified margin applied.

    Example

    const extent = new Extent('EPSG:3857', 0, 100, 0, 100);
    const margin = extent.withRelativeMargin(0.1);
    // new Extent('EPSG:3857', -10, 110, -10, 110);
  • Constructs an extent from the specified box.

    Parameters

    • crs: string

      the coordinate reference system of the new extent.

    • box: Box3

      the box to read values from

    Returns Extent

    the constructed extent.

  • Returns an extent centered at the specified coordinate, and with the specified size.

    Parameters

    • crs: string

      The CRS identifier.

    • center: {
          x: number;
          y: number;
      }

      The center.

      • x: number
      • y: number
    • width: number

      The width, in CRS units.

    • height: number

      The height, in CRS units.

    Returns Extent

    The produced extent.