regrid: Change raster image resolution and extent
In ursa: Non-Interactive Spatial Tools for Raster Processing and Visualization

regrid

R 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, adjust = c(0.5, 0.5), verbose = FALSE, ...)

Arguments

`x`	Object of class `ursaRaster`.
`...`	Arguments, which are passed to non-public `.regrid` to define parameters of new grid. 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`.
`adjust`	`numeric` of length 2. Dragging horizontal and vertical expansion for argument `expand`. Value `0.0` means expansion to the left or to the bottom. Value `1.0` means expansion to the right or to the top. Value `0.5` means equal horizontal or vertical expansion. Default is `c(0.5,0.5)`.
`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

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)

ursa documentation built on Sept. 30, 2024, 9:35 a.m.