regrid: Change raster image resolution and extent

regridR Documentation

Change raster image resolution and extent

Description

General function to change parameters of cells under the same geographical projection. It is implemented via raster resampling to the new grid.

Usage

regrid(x, ...)

## non-public
.regrid(grid = NULL, mul = NA, res = NA, resx = NA, resy = NA, setbound = NA,
        columns = NA, rows = NA, dim = NA, bbox = NA, expand = NA,
        minx = NA, miny = NA, maxx = NA, maxy = NA, cut = NA, proj4 = NA, crs = NA,
        border = 0, zero = c("keep", "node", "center"), raster = FALSE, tolerance = NA,
        zoom = NA, verbose = FALSE, ...)

Arguments

x

Object of class ursaRaster.

...
  1. Arguments, which are passed to non-public .regrid to define parameters of new grid.

  2. Set of arguments, which are recognized via their names (using regular expressions) and classes:

    ^reset(Grid)*

    Logical. Whether new grid will be defined as a sessional parameter? If TRUE then returned raster defines new sessional grid. If FALSE then session grid is not changed. Default is TRUE.

    resample

    Logical or positive numeric. The range of aggregation in the units of cell area. If 0 or FALSE then "nearest neighbor" value is used. The resample>0 defines the side of rectangular area in proportion to cell size; and aggregation of adjacent cells is weighted in proportion to overlapping parts of cells. Default is 1 (or, equally, TRUE); it means that value of output cell is weighted mean of values of overlapped input cells in proportion of overlapping of output cell by input cells.

    cover

    Positive numeric in the range [0, 1]. The maximal fraction of NA values in adjusted input cells for the rule to write NA value to the output cell. Default is 0.499.

    cascade

    Logical. Option to get more smooth results. If TRUE and resample>2 then resize function is applied sequentially with argument resample<=2.

    verb(ose)*

    Logical. Value TRUE may provide some additional information on console. Default is FALSE.

grid

Reference ursaGrid or ursaRaster object. If missing then reference grid is obtained from sessional grid session_grid()

mul

numeric of length 1. Multiplication for changing image size by means of changing of cell size (1/mul). mul>1 decreases cell size, mul<1 increases cell size

res

numeric of length 1 or 2. New grid size by horizontal and vertical axes. If length is 1 then the same grid size for both axes.

resx

Positive numeric of length 1. New grid size by horizontal axis.

resy

Positive numeric of length 1. New grid size by vertical axis.

setbound

numeric of length 4. Change units of spatial extension and define new spatial extension (boundary box) in the notation c(minx,miny,maxx,maxy).

columns

Positive integer of length 1. Number of columns/samples in the case of definition of new spatial extension (setbound is non-NA).

rows

Positive integer of length 1. Number of rows/lines in the case of definition of new spatial extension (setbound is non-NA).

dim

Positive integer of length 2. Dimenstion of raster image in the notation c(rows, columns) (or, c(lines, samples)) in the case of definition of new spatial extension (setbound is non-NA).

bbox

numeric of length 4. New spatial extension (boundary box) in the notation c(minx,miny,maxx,maxy) in the same units of existing spatial extension.

minx

numeric of length 1. New value for left boundary.

miny

numeric of length 1. New value for bottom boundary.

maxx

numeric of length 1. New value for right boundary.

maxy

numeric of length 1. New value for top boundary.

cut

numeric of length 4. Vector (left, bottom, right, top) in CRS units for extent expand.

border

numeric of length 1 or 4. If length 4, then vector (bottom, left, top, right) in cells for extent expand. If length <4, then value is repeated for length 4.

proj4

character of length 1. New projection string in the PROJ.4 notation

crs

character of length 1. The synonym to proj4.

expand

numeric of length 1. Multiplier of boundary box.

raster

logical. Should return blank ursaRaster object instead of ursaGrid object? See ‘Value’ section

zero

character. Define central cell position relative to zero coordinates. If value is "keep", then central cell position is without changes. If value is "node", then zero coordinates are on the crossing of cell borders. If value is "center", then zero coordinates are in the center of central cell. Currently is not implemented. If grid is consistent, then value "keep" is used, else "node".

tolerance

numeric. Threshold for comparison float point numerics. Required for internal check of grid consistence. Default is NA; value .Machine$double.eps multiplied on maximal value of coordinates is used.

zoom

numeric. Tweak for simultaneous change of expand and mul: expand=zoom, mul=1/zoom. Default is NA.

verbose

Reporting via message about violation and restoration of coordinate grid regilarity after non-consistence usage of parameters.

Details

Generally, argument resample sets a rectangular region. The area of this region is in proportion to area of output cell. Argument resample is the value of this proportion. Each cell is interpreted as a set of adjoining rectangular figures. The value of output cells is a weighted mean of that input cells, which fall into rectangular region. The weights are defined as an partial area inside of rectangular region.

Function implements "nearest neighbor" resampling method if argument resample=0 (or, resample=FALSE). If resample=1 (or, resample=TRUE) and both input and output rasters have the same cell size, then resampling method is "bilinear interpolation".

Expand raster x to 3 times with cell repeating: regrid(x,mul=3,resample=FALSE) ## nearest neighbor;
Expand raster x to 3 times with cell aggregation: regrid(x,mul=3,resample=TRUE) ## bilinear interpolation;
Contract raster x to 3 times without cell aggregation: regrid(x,mul=1/3,resample=FALSE) ## nearest neighbor;
Contract raster x to 3 times with cell aggregation: regrid(x,mul=1/3,resample=TRUE) ## weighted mean;
Low-pass filtering by 3 x 3 window size: regrid(x,resample=3*3) ## see focal_mean

However, simple contraction regrid(x,mul=1/2,resample=FALSE) is implemented as contration with aggregation (regrid(x,mul=1/2,resample=FALSE)), because centers or output cells are located in the nodes (crossing of boundaries of input cells).

It seems that for categorical rasters parameter resample=0 is more suitable, because nearest neigboring does not introduce new values to output raster, excepting coincidence of input cells' nodes and output cell centers.

Usage of proj4 argument specifies only desirable PROJ.4 string and does not do reprojection.

The violation of grid regualarity is due to columns and rows of image should be integer. The restoration of grid regularity is realized by spatial extension (boundary box) expansion.

Value

regrid returns object of class ursaRaster.

Return value of non-public function .regrid depends on logical value of raster argument. If raster=FALSE then .regrid returns new grid without any change of sessional grid. If raster=TRUE then .regrid returns blank image and changes sessional grid.

Author(s)

Nikita Platonov platonov@sevin.ru

See Also

regrid, focal_mean

Examples

session_grid(NULL)
print(g1 <- session_grid())
print(g2 <- regrid(g1,mul=2))
print(g3 <- regrid(g1,res=50000,lim=c(-1200000,-1400000,1600000,1800000)))
print(g4 <- regrid(g1,res=50000,lim=c(-1200100,-1400900,1600900,1800100),verbose=TRUE))
print(g5 <- regrid(g1,mul=1/4))
print(g6 <- regrid(g1,mul=1/4,cut=c(-1,-2,3,4)*25000))
print(g7 <- regrid(g1,mul=1/4,expand=1.05))
print(session_grid()) ## equal to 'g1'
print(a <- regrid(g1,mul=1/4,border=3,raster=TRUE))
print(session_grid()) ## not equal to 'g1'

session_grid(NULL)
'.makeRaster' <- function(nc=6,nr=8) {
   as.ursa(t(matrix(runif(nc*nr,min=0,max=255),ncol=nc,nrow=nr)))
}
session_grid(NULL)
a <- .makeRaster(12,18)
expand <- 1/3
a1 <- regrid(regrid(a,mul=expand,resample=FALSE),a,resample=FALSE)
a2 <- regrid(regrid(a,mul=expand,resample=TRUE),a,resample=FALSE)
b <- c('source'=a,'contract'=a1,'aggregation'=a2)
print(b)
display_brick(b,grid=TRUE
             ,grid.lon=(seq(ncol(a)*expand+1)-1)/expand
             ,grid.lat=(seq(nrow(a)*expand+1)-1)/expand)
session_grid(NULL)
a <- .makeRaster(6,8)
expand <- 3
b <- c("source"=regrid(a,mul=expand,resample=FALSE,resetGrid=FALSE)
      ,"simple"=regrid(a,mul=expand,cascade=TRUE,resetGrid=FALSE)
      ,"cascaded"=regrid(a,mul=expand,cascade=FALSE,resetGrid=FALSE))
print(b)
display_brick(b)
session_grid(a)
eps <- 1e-4
r <- c(0,expand^(-2)-eps,expand^(-2)+eps,1,expand^0.5
      ,(expand+2/3)^2-eps,(expand+2/3)^2+eps,99)
g2 <- regrid(mul=expand)
session_grid(g2)
b <- ursa_new(bandname=sprintf("Resample=%.4f",r))
for (i in seq(b))
   b[i] <- regrid(a,g2,resample=r[i])
print(b)
display_brick(b,layout=c(2,NA)
             ,grid=TRUE,grid.lon=seq(ncol(a)+1)-1,grid.lat=seq(nrow(a)+1)-1)

nplatonov/ursa documentation built on Feb. 2, 2024, 4:08 a.m.