Package 'ursa'

Description

Have a great work with ursa!

Details

See table of content.

Author(s)

Nikita Platonov [email protected]

Description

allocate takes x and y coordinates and values from data frame, which is describing point spatial data, and puts them into cells of raster. The certain function (either mean value, sum of values, number of points) is applied for >0 points inside of the exact cell borders.

Usage

allocate(vec, coords = c("x", "y"), nodata = NA, attr = ".+", fun = c("mean", "sum", "n"),
         cellsize = NA, resetGrid = FALSE, verbose = FALSE)

Arguments

Details

Here fun differs from R-styled fun in such functions as *apply, aggregate.

It was refused “rasterize” for function name to distinguish with rasterize in the package raster

Value

Object of class ursaRaster

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
g1 <- session_grid(regrid(session_grid(),mul=1/10))
n <- 1000
x <- with(g1,runif(n,min=minx,max=maxx))
y <- with(g1,runif(n,min=miny,max=maxy))
z <- with(g1,runif(n,min=0,max=10))
da <- data.frame(x=x,y=y,value=z)
res <- c(mean=allocate(da,fun="mean")
        ,mean_=NA
        ,sum=allocate(da,fun="sum")
        ,count=allocate(da,fun="n"))
res["mean_"]=res["sum"]/res["count"]
print(res)

Description

Coercion from raster ursaRaster object to raster stars object defined in package stars.

Usage

as_stars(obj)

Arguments

Details

Simple coercion to stars object of package stars. Currently, color tables and attribution tables are not supported.

Value

Object of class stars for argument of class ursaRaster. Otherwise, NULL.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
a <- ursa_dummy(3)
x <- as_stars(a)
class(x)
if (requireNamespace("stars")) {
   print(x)
   b <- as_ursa(x)
   print(a)
   print(b)
}

Description

In the ursaRaster object the 3-dimensional image data are presented in 2-dimensional matrix. as.array transforms internal 2-dimensional data to the usual 3-dimansional data. as.matrix just extracts image data in internal 2-dimensional format.

Usage

## S3 method for class 'ursaRaster'
as.array(x, ...)

## non-public
.as.array(x, drop = FALSE, flip = FALSE, permute = FALSE, dim = FALSE)

Arguments

Details

Use permute=TRUE to create an object of class raster: as.raster(as.array(...))

The spatial reference system is lost.

Value

If dim=FALSE then as.array returns object of class array.
If dim=TRUE then as.array returns dimension of array.
as.matrix returns object of class matrix.

Author(s)

Nikita Platonov [email protected]

See Also

as.raster is a function to direct export to the object of class raster.
as.matrix with argument/value coords=TRUE and as.data.frame for object of class ursaRaster keep spatial reference system.

Examples

session_grid(NULL)
a <- pixelsize()
a <- (a-global_min(a))/(global_max(a)-global_min(a))
b <- c(entire=a,half=a/2,double=a*2)
str(m <- as.matrix(b))
str(d1 <- as.array(b))
str(d2 <- as.array(b[1],drop=FALSE))
str(d3 <- as.array(b[1],drop=TRUE))
contour(d3)
filled.contour(d3)
d4 <- as.array(b,perm=TRUE)/global_max(b)
d4[is.na(d4)] <- 0
str(d4 <- as.raster(d4))
plot(d4)

Description

as.data.frame reorganizes ursaRaster object into data frame, where first two columns (x and y) are coordinates of cells, and the rest columns are cell values.

Usage

## S3 method for class 'ursaRaster'
as.data.frame(x, ...)

# non-public
.as.data.frame(obj, band = FALSE, id = FALSE, na.rm = TRUE, all.na = FALSE,
               col.names = NULL)

Arguments

Details

The structure of voxel is kept. The number of rows for band=TRUE is equal to the number of rows for band=FALSE multiplied to number of bands. To extract all numeric data with destroying of voxel, you may use followed code:
subset(as.data.frame(obj,band=TRUE),!is.na(z)).

Value

Data frame.

If band=TRUE then

If band=FALSE then

If ursaRaster is projected, then data frame has additional attribute attr(...,"proj") with value of PROJ.4 string.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
session_grid(regrid(res=50000,lim=c(-1200100,-1400800,1600900,1800200)))
a0 <- ursa_dummy(nband=3,min=0,max=100)
a0[a0<30 | a0>70] <- NA
names(a0) <- c("x","y","z")
print(a0)
b0 <- as.data.frame(a0)
session_grid(NULL)
a1 <- as.ursa(b0)
print(a1-a0)
session_grid(NULL)
session_grid(regrid(res=5800000))
set.seed(352)
a2 <- as.integer(ursa_dummy(nband=2,min=0,max=100))
a2[a2>50] <- NA
print(a2)
print(b1 <- as.data.frame(a2,na.rm=FALSE))
print(b2 <- as.data.frame(a2,na.rm=TRUE))
print(b3 <- as.data.frame(a2,all.na=TRUE))
print(b4 <- as.data.frame(a2,band=TRUE,na.rm=FALSE))
print(b5 <- as.data.frame(a2,band=TRUE,all.na=FALSE))
print(b6 <- as.data.frame(a2,band=TRUE,all.na=TRUE))
print(b7 <- as.data.frame(a2,band=TRUE,all.na=TRUE,id=TRUE))

Description

as.integer for object of class ursaRaster truncates decimal part of image values and then converts to type integer.

Usage

## S3 method for class 'ursaRaster'
as.integer(x, ...)

Arguments

Value

Object of class ursaRaster where storage.mode of values is integer.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
a <- pixelsize()
a <- a-min(a)+0.5
str(ursa_value(a))
print(storage.mode(a$value))
b <- as.integer(a)
str(ursa_value(b))
print(storage.mode(b$value))

Description

as.matrix(coords=TRUE) prepares a list from the first band of ursaRaster, which is suitable as input parameter for functions image, contour and filled.contour.

Usage

## S3 method for class 'ursaRaster'
as.matrix(x, ...)
## S3 method for class 'ursaRaster'
x[[i]]

Arguments

Details

Item colortable is mainly for internal usage, e. g., for mapping. Item proj is useful for convertion back to ursaRaster object by calling as.ursa function.

Extract operator x[[i]] is a wrapper for as.matrix(x[i],coords=TRUE)

Value

Depending of argument coords.

If coords=FALSE, then it is a two-dimensional matrix c(samples*lines, bands), unclassed from ursaValue class.

If coords=TRUE, then it is a list:

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
a <- ursa_dummy(nband=3,min=0,max=100)
a <- a[a>=20 & a<=80]
ignorevalue(a) <- 121
str(ursa_value(a[2]))
str(as.matrix(a[2]))
b1 <- a[[2]]
str(b1)
image(b1,asp=1)
b2 <- as.matrix(a[2:3],coords=TRUE)
print(c('theSame?'=identical(b1,b2)))
a2 <- as.ursa(b2)
res <- c(src=a[2],exported_then_imported=a2,diff=a[2]-a2)
print(res)

Description

as.raster transforms object of class ursaRaster to the object of class raster (package grDevices)

Usage

## S3 method for class 'ursaRaster'
as.raster(x, ...)

Arguments

Value

A raster object. It is a matrix. The values of matrix are colors.

Author(s)

Nikita Platonov [email protected]

See Also

as.array

Examples

session_grid(NULL)
session_grid(regrid(mul=1/2))
a <- ursa_dummy(4,min=0,max=255)
a[a<70] <- NA
compose_open(layout=c(1,4),legend=NULL)
for (i in seq(4)) {
   panel_new()
   panel_plot(as.raster(a[seq(i)]),interpolate=FALSE)
   panel_annotation(paste("Number of channels:",i))
}
compose_close()

op <- par(mfrow=c(2,2),mar=rep(0.5,4))
plot(as.raster(a[1:1]),interpolate=FALSE)
plot(as.raster(a[1:2]),interpolate=FALSE)
plot(as.raster(a[1:3]),interpolate=FALSE)
plot(as.raster(a[1:4]),interpolate=FALSE)
par(op)

Description

as.Raster converts singe-band ursaRaster object to raster, multi-band ursaRaster object to brick and list of ursaRaster objects to stack. S4 classes “raster”, “brick”, and “stack” are defined in package raster.

Usage

as.Raster(obj)

## S3 method for class 'ursaRaster'
as.Raster(obj)

## S3 method for class 'list'
as.Raster(obj)

## S3 method for class 'ursaStack'
as.Raster(obj)

## S3 method for class 'NULL'
as.Raster(obj)

Arguments

Details

Package raster is required for conversions.

The uppercase ⁠as.⁠⁠R⁠⁠aster⁠ is important, because as.raster is used in internal functions for coercion to object of class raster.

Single-banded ursaRaster object (with or without colortable) is coerced to RasterLayer. Colortables are kept.
Multi-banded ursaRaster object is coerced to RasterBrick. Colortables are destroyed.
Multi-layered object (list of ursaRaster objects) is coerced to RasterStack. Colortables are destroyed.

Value

Either RasterLayer, RasterBrick, or RasterStack object.

If package raster is not installed then return value is NULL

Note

Package raster is marked as "Suggested".

Author(s)

Nikita Platonov [email protected]

Examples

## test is skipped: raster's loading time is close to CRAN allowable test time
session_grid(NULL)
if (requireNamespace("raster")) {
   session_grid(regrid(mul=1/4))
   msk <- ursa_dummy(1,min=0,max=100)>40
   a1 <- ursa_dummy(1,min=200,max=500)[msk]
   a2 <- colorize(a1,ramp=FALSE)
   a3 <- as.integer(ursa_dummy(3,min=0,max=255.99))
   a4 <- ursa_stack(a3[msk])
   if (isLayer <- TRUE) {
      print(a1)
      r1 <- as.Raster(a1)
      message(as.character(class(r1)))
      print(r1)
      print(raster::spplot(r1))
      b1 <- as.ursa(r1)
      print(c(exported=a1,imported=b1,failed=b1-a1))
      print(c(theSameValue=identical(ursa_value(a1),ursa_value(b1))
             ,rheSameGrid=identical(ursa_grid(a1),ursa_grid(b1))))
   }
   if (isLayerColortable <- TRUE) {
      r2 <- as.Raster(a2)
      message(as.character(class(r2)))
      print(r2)
      print(raster::spplot(r2))
      b2 <- as.ursa(r2)
      print(c(theSameValue=identical(ursa_value(a2),ursa_value(b2))
             ,rheSameGrid=identical(ursa_grid(a2),ursa_grid(b2))))
   }
   if (isBrickOrRGB <- TRUE) {
      r3 <- as.Raster(a3)
      message(as.character(class(r3)))
      print(r3)
      print(raster::spplot(r3))
      raster::plotRGB(r3)
      b3 <- as.ursa(r3)
      print(c(theSameValue=identical(ursa_value(a3),ursa_value(b3))
             ,rheSameGrid=identical(ursa_grid(a3),ursa_grid(b3))))
   }
   if (isStack <- TRUE) {
      r4 <- as.Raster(a4)
      message(as.character(class(r4)))
      print(r4)
      print(raster::spplot(r4))
      b4 <- as.ursa(r4)
      print(c(theSameValue=identical(ursa_value(a4),ursa_value(b4))
             ,theSameGrid=identical(ursa_grid(a4),ursa_grid(b4))))
   }
}

Description

as.table is an implementation of function base::table for values of raster image.

Usage

## S3 method for class 'ursaRaster'
as.table(x, ...)

ursa_table(x, ...)

Arguments

Details

If ursaRaster has a colortable, then values are replaced by names of categories.

ursa_table is synonym to method as.table for class `ursaRaster`.

Value

Object of class table.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
a <- colorize(pixelsize(),nbreak=4)
t1 <- as.table(a)
print(t1)
str(t1)
ursa_colortable(a) <- NULL
t2 <- as.table(a)
print(t2)

Description

as.ursa converts R base objects matrix, array, numeric, data.frame list, sp objects SpatialGridDataFrame, SpatialPixelsDataFrame and SpatialPointsDataFrame, raster objects raster, stack and brick, and GDAL raster files (using functions from rgdal package) to ursaRaster object.

Usage

as.ursa(obj, ...)
as_ursa(obj, ...)

Arguments

Details

as_ursa is a synonym to as.ursa.

This is a high-level function to create ursaRaster objects. The follwed classes of R objects are implemented:

Generally, allocate is used for objects with non-regular grid, and ursa_new is used for regular grids. The raster grid is defined from object properties or from sessional grid.

Color tables are supported for GDAL file names and raster objects (raster, brick, stack).

For ENVI *.hdr Labelled Raster Files there are alternatives:

1. Read object with GDAL (read_gdal);

2. Read object without GDAL (read_envi).

Value

Object of class ursaRaster

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
a1 <- as.ursa(volcano)
print(a1)
display(a1)

session_grid(NULL)
b <- ursa_dummy(mul=1/16,bandname=format(Sys.Date()+seq(3)-1,"%A"))
print(b)

c1 <- b[[1]] ## equal to 'c1 <- as.matrix(b[1],coords=TRUE)'
str(c1)
b1a <- as.ursa(c1)
print(c(original=b[1],imported=b1a))
print(c(projection.b1a=ursa_proj(b1a)))
session_grid(NULL)
b1b <- as.ursa(c1$z)
print(b1b)
print(c(projection.b1b=ursa_proj(b1b)))

c2 <- as.data.frame(b)
str(c2)
session_grid(NULL)
b2a <- as.ursa(c2)
print(b2a)

session_grid(NULL)
attr(c2,"crs") <- NULL
b2b <- as.ursa(c2)
print(b2b)
print(ursa_grid(b2b))

c3 <- unclass(as.matrix(b,coords=TRUE))
str(c3)
session_grid(b)
b3a <- as.ursa(c3)
print(b3a)
print(ursa_grid(b3a))
session_grid(NULL)
b3b <- as.ursa(c3)
print(b3b)
print(ursa_grid(b3b))

c4 <- as.array(b)
str(c4)
session_grid(b)
b4a <- as.ursa(c4)
print(b4a)
print(ursa_grid(b4a))
session_grid(NULL)
b4b <- as.ursa(c4)
print(b4b)
print(ursa_grid(b4b))

n <- 20
c5 <- data.frame(y=runif(n,min=1000000,max=5000000)
                ,x=runif(n,min=-3000000,max=1000000)
                ,value=runif(n,min=0,max=10))
print(head(c5))
session_grid(b)
b5a <- as.ursa(c5)
print(b5a)
 ## to avoid over-timing during tests -- begin
   display(b5a)
 ## to avoid over-timing during tests -- end
session_grid(NULL)
b5b <- as.ursa(c5)
print(b5b)
 ## to avoid over-timing during tests -- begin
   display(b5b)
 ## to avoid over-timing during tests -- end

# b6 <- as.ursa(system.file("pictures/erdas_spnad83.tif",package="rgdal"))
b6 <- as.ursa(system.file("tif/geomatrix.tif",package="sf"))
print(b6)
display(b6,pal=c("black","white"),coast=FALSE,col="orange")

 ## package 'raster' is required -- begin
if (requireNamespace("raster")) {
   r <- raster::brick(system.file("external/rlogo.gri",package="raster"))
   print(r)
   b7 <- as.ursa(r)
   ursa_proj(b7) <- ""
   print(b7)
   display_rgb(b7)
}
 ## package 'raster' is required -- end

Description

Function from this band.* list returns required statistics for each band.

Usage

band_mean(obj)
band_sd(obj)
band_sum(obj)
band_min(obj)
band_max(obj)
band_n(obj)
band_nNA(obj)
band_quantile(obj, ...)

Arguments

Details

• band_mean returns mean value.

• band_sd returns value of standard deviation with n-1 denominator.

• band_sum returns sum of values.

• band_min returns minimal value.

• band_max returns maximal value.

• band_n returns number of non-NA pixels.

• band_nNA returns number of NA pixels.

• band_quantile returns matrix of quantiles.

Value

Named vector of numerical or integer values. Band names are used for naming.

Note

Currently, implementation is not optimal, because firstly bundle of statistics is computed using band_stat function, and then required statistics is extracted.

Author(s)

Nikita Platonov [email protected]

See Also

band_stat

Examples

session_grid(NULL)
a <- ursa_dummy()
print(a)
print(a<80)
print(class(a))
a[a<80]
a[a<80] <- NA
b1 <- band_stat(a)
print(b1)
b2.n <- band_n(a)
str(b2.n)
b2.mean <- band_mean(a)
print(b1$mean)
print(b2.mean)
print(b1$mean-b2.mean)
print(band_quantile(a))

Description

For each band of ursaRaster object, band_stat returns certain statistics (mean, sd, sum, min, max, number of non-NA pixels, number of NA pixels). Regarding to each band, it is global operations of map algebra.

Usage

band_stat(x, grid = FALSE, raw = FALSE)

Arguments

Details

If raster values are not in memory or grid=TRUE then ursa_info is returned.

Generic function print for object of class ursaRaster uses returned value of band_stat function with formatted columns.

Statistics is computed for omitted NA values.

Value

data.frame. Row names are indices of bands. Column names are:

Author(s)

Nikita Platonov [email protected]

See Also

Columns extraction from returned data frame is in the group of band.* functions.

Examples

session_grid(NULL)
s <- substr(as.character(sessionInfo()),1,48)
a <- reclass(ursa_dummy(mul=1/2,bandname=s),ramp=FALSE)
band_stat(a,grid=TRUE)
b2 <- band_stat(a)
b3 <- band_stat(a,raw=TRUE)
str(b2)
str(b3)
print(b2)
print(a) ## 'print.ursaRaster' uses 'band_stat'
print(a,raw=TRUE)

Description

bandname (names) returns names of bands for object of class ursaRaster or existing ENVI labelled *.hdr file. bandname<- (names<-) sets names of bands for object of class ursaRaster.

Usage

bandname(x)
bandname(x) <- value

## S3 method for class 'ursaRaster'
names(x)

## S3 replacement method for class 'ursaRaster'
names(x) <- value

Arguments

Details

names is a synonym for bandname. names<- is a synonym for bandname<-

Value

For bandname and names, character vector.

For bandname<- and names<-, updated object of class ursaRaster.

Author(s)

Nikita Platonov [email protected]

See Also

nband

Examples

session_grid(NULL)
a1 <- pixelsize()
a2 <- c("Band 1"=a1,Band2=a1/2,sqrt=sqrt(a1),NA)
print(a2)
print(bandname(a2))
bandname(a2)[1:2] <- c("Original","Half")
print(a2)
print(bandname(a2))

Description

Set of functions for checking is any or all bands have no data, and for retrieving indices for non-data bands.

Usage

band_blank(obj, ref = c("any", "0", "NA"), verbose = FALSE)
ursa_blank(obj, ref)

Arguments

Details

It is defined locally that if all values of band are NA or 0 (see description to argument ref), then such band is blank. The fact is ursa_new create new object in memory with default values NA, but create_envi writes zeros to disk quick. It is decided to consider both these cases as blank. Function band_blank checks blanks for each band of image. If all bands are blank then function ursa_blank returns TRUE.

Value

Function ursa_blank returns logical value of length 1.

Function band_blank returns logical value of length nband(obj).

Author(s)

Nikita Platonov [email protected]

See Also

is.na returns object of class ursaRaster; it is mask of cells, which have NA value.

Examples

session_grid(NULL)
a <- ursa_new(bandname=c("first","second","third","fourth"))
ursa_value(a,"first") <- 0 ## 'a[1] <- 1' works, but it is slow
print(ursa_blank(a))
a[3] <- pixelsize()
a[4] <- a[3]>625
print(a)
print(band_blank(a))
print(which(band_blank(a)))
print(ursa_blank(a))

Description

This function is an instrument for appending bands or for reorganizing bands.

Usage

## S3 method for class 'ursaRaster'
c(...)

Arguments

Details

You may use this function to assign new bandname for single-band raster: objDst <- c('Relative density'=objSrc)

Use also 'Extract' operator [ ] to reorganize band sequence.

The returned object can be interpreted as a brick in the notation of package raster. To produce stack just call list or ursa_stack.

Value

ursaRaster object.

Author(s)

Nikita Platonov [email protected]

See Also

ursa_brick converts list of ursaRaster objects (stack) to a singe multiband ursaRaster object (brick).

Examples

session_grid(NULL)
session_grid(regrid(mul=1/16))
a1 <- ursa_dummy(nband=2)
names(a1) <-  weekdays(Sys.Date()+seq(length(a1))-1)
a2 <- ursa_dummy(nband=2)
names(a2) <- names(a1)
print(a1)
print(a2)
a3 <- a1[1]
print(names(a3))
a4 <- c(today=a3)
print(names(a4))
print(b1 <- c(a1,a2))
print(b2 <- c(a1=a1))
print(b3 <- c(a1=a1,a2=a2))
print(b5 <- c(a1=a1,a2=a2[1]))
print(b4 <- c(a1,'(tomorrow)'=a1[2])) ## raster append
print(b6 <- c(a1,50))

Description

In the case of 'Cannot allocate vector of size ...' error message chunk_band returns list of bands indices, which are suitable for allocation in memory at once, chunk_line returns list of lines (rows) indices, which are suitable for allocation in memory at once. chunk_expand is used to expand lines indices and can by applied in focal functions.

Usage

chunk_band(obj, mem = 100, mul = 1)
chunk_line(obj, mem = 100, mul = 1)
chunk_expand(ind, size = 3)

Arguments

Value

chunk_band returns list with sequences of bands

chunk_line returns list with sequences of lines

chunk_expand returns list:

Author(s)

Nikita Platonov [email protected]

Examples

## 1. Prepare data
 session_grid(NULL)
 fname <- ursa:::.maketmp(2)
 a <- create_envi(fname[1],nband=3,ignorevalue=-99)
 for (i in seq(nband(a)))
   a[i] <- pixelsize()^(1/i)
 close(a)
 rm(a)
 
 ## 2. Read 
 a <- open_envi(fname[1])
 chB <- chunk_band(a,2)
 str(chB)
 for (i in chB)
    print(a[i])
 chL <- chunk_line(a,2.5)
 str(chL)
 for (j in chL)
    print(a[,j])
 
 ## 3. Filtering with partial reading
 b <- create_envi(a,fname[2])
 fsize <- 15
 for (j in chL) {
    k <- chunk_expand(j,fsize)
    b[,j] <- focal_mean(a[,k$src],size=fsize)[,k$dst]
 }
 d1 <- b[]
 
 ##  4. Filtering in memory
 d2 <- focal_mean(a[],size=fsize)
 close(a,b)
 envi_remove(fname)
 print(d1-d2)
 print(round(d1-d2,4))

Description

close() for ursaRaster object closes connection for opened file using inheritted function base::close. Function close_envi() closes opened connection for ENVI binary file.

Usage

## S3 method for class 'ursaRaster'
close(...)

close_envi(...)

Arguments

Value

NULL

Author(s)

Nikita Platonov [email protected]

See Also

close of base package

Examples

session_grid(NULL)
a <- create_envi()
fname <- a$con$fname
message(paste("Created file",dQuote(basename(fname)),"will be deleted."))
print(dir(pattern=basename(envi_list(fname))))
close(a)
invisible(envi_remove(fname))

Description

compress reduces dimension of source image matrix and assigns indices. decompress uses indices for expansion of reduced image matrix.

Usage

decompress(obj)
compress(obj)

Arguments

Details

After masking, vectorization of lines, points and small polygons image matrix is often sparse. Compressing (compress) is an option to reduce object size in memory. Decompressing (decompress) restore original data matrix.

Value

Object of class ursaRaster

Note

Currently, usage of compressed image matrix is limited. Spatial filtering (e.g. focal_mean) does not operate with compressed data.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
b <- as.data.frame(pixelsize())
b <- subset(b,x>1000000 & x<2000000 & y>3000000 & y<4000000)
a1 <- as.ursa(b)
print(a1)
print(object.size(a1))
a2 <- compress(a1)
print(a2)
print(object.size(a2))
a3 <- decompress(a2)
print(a3)
print(object.size(a3))
print(identical(a1,a3))

Description

colorize assigns color table to raster image.

Usage

colorize(obj, value = NULL, breakvalue = NULL, name = NULL, pal = NULL, inv = NA,
         stretch = c("default", "linear", "equal", "mean", "positive",
                     "negative", "diff", "category", "julian", "date", "time",
                     "slope", "conc", "sd", "significance", "bathy",
                     "grayscale", "greyscale", ".onetoone"),
         minvalue = NA, maxvalue = NA, byvalue = NA, ltail = NA, rtail = NA, tail = NA,
         ncolor = NA, nbreak = NA, interval = 0L, ramp = TRUE, byte = FALSE,
         lazyload = TRUE, reset = FALSE, origin = "1970-01-01" ,format = "",
         alpha = "", colortable = NULL, verbose = FALSE, ...)
                          
palettize(...) ## wrapper for non-spatial vectors

Arguments

Details

palettize is a wrapper ursa_colortable(colorize(...)) to return color table for one-dimensional numeric or character vector.

colortable is designed to prepare pretty thematic maps.

Color rampimg (ramp=TRUE) is not quick in computatons and has no effective labelling. It is intoduced to visualize non-thematic maps, and it is assumed that labeling can be omitted for such maps.

The labelling implementation is based on some improvements of pretty function. The notation of intervals is mixed by brackets and comparative symbols, for example: "<=1.5","(1.5,2.5]","(2.5,3.5]",">3.5"

Reserved values for interval:

• 0L or FALSE - no interlavs. Values are interpreted as category, even if they are in non-nominal scale

• 1L or TRUE - each category corresponds to interval. The low limit of lowest category is -Inf. The high limit of highest category is +Inf

• 2L - different implementation of interval=1. In some cases may relult more pretty labeling.

  If breaks is numerical vector and colors has zero length, then it is assumed interal scaling, and interval=1L is assigned to unspecified interval

  Finite values of extreme intervals are neccessary sometimes, however this option is not implemented currently

Keywords for stretch to create pre-defined color tables:

• "positive" - lower limit is 0. Palette is "Oranges"

• "negative" - higher limit is 0. Palette is "Purples"

• "grayscale", "greyscale" - palette is "Greys". Usually used for raw satellite images.

• "mean" - designed for common thematic maps and for averaged map across set of maps. Palette is "Spectral"

• "sd" - designed for spatial mapping of standard deviation across set of maps. Palette is "YlGnBu"

• "diff" - diverge palette "RdBu". Absolute values of lower and upper limits are equal, zero is in the middle of palette. Designed for anomaly maps.

• "slope" - is similar to diff but without extreme colors, which are reserved for contouring of statistically significant areas.

• "significance" - desiged to illustrate statistically significant areas of slope. The realisation is colortable(obj, value=c(-0.999, -0.99, -0.95, -0.9, -0.5, +0.5, +0.9, +0.95, +0.99, +0.999), interval=1L, palname="RdBu")

• "category" - Values are interpreted in nominal scale. Palette is based on random colors from "Pairs" palette.

• "conc" - designed for visualization of sea ice concentration data, which have lower limit 0 and higher limit 100. Palette is "Blues"

• "bathy" - designed for ocean depth (bathymetry) maps. Internally colorize(obj, stretch="equal",interval=1L, palname="Blues", inv=TRUE) is used to detect the crossing from shelf waters to deep water basin. Better practice is to do second step with manual specification of value argument.

• "internal" - continuous colors, designed for conversion to greyscale with keeping of intensities.

• "default" - allowing to detect stretch by intuition, without any strong mathematical criteria

It is allowed manual correction of labels using followed code example: names(ursa_colortable(x)) <- c("a<=0","0<a<=1","a>1")

Value

Object of class ursaRaster with named character vector of item $colortable

Author(s)

Nikita Platonov [email protected]

See Also

ursa_colortable, ursa_colortable<-

Examples

session_grid(NULL)
a <- pixelsize()-350
print(a)
b1 <- colorize(a,ramp=FALSE)
print(ursa_colortable(b1))
b2 <- colorize(a,interval=1,stretch="positive",ramp=FALSE)
print(ursa_colortable(b2))
b3 <- colorize(a,interval=2,stretch="positive",ramp=FALSE)
print(ursa_colortable(b3))
b4 <- colorize(a,value=c(150,250),interval=1)
print(ursa_colortable(b4))
names(ursa_colortable(b4)) <- c("x<=150","150<x<=250","x>250")
print(ursa_colortable(b4))
display(b4)

Description

Manipulation with color tables of raster images.

Usage

## S3 method for class 'ursaColorTable'
print(x, ...)

## S3 method for class 'ursaColorTable'
x[i]


ursa_colortable(x)

ursa_colortable(x) <- value

ursa_colorindex(ct)
   
ursa_color(ct, ...)

## S3 method for class 'ursaColorTable'
names(x)

## S3 replacement method for class 'ursaColorTable'
names(x) <- value

Arguments

Details

The example of the class structure

Class 'ursaColorTable'  Named chr [1:4] "#313695" "#BCE1EE" "#FDBE70" "#A50026"
  ..- attr(*, "names")= chr [1:4] "<= 450" "(450;550]" "(550;650]" "> 650"

It is recommended to use ursa_colortable and ursa_colortable<- instead of colortable and colortable<-. ursa_colortable and colortable are synonyms. ursa_colortable<- and colortable<- are synonyms too. Package raster contains colortable and colortable<- functions. colortable and colortable<- will be remove from this package if the case of frequent joint use of both packages.

If color tables describe continuous and non-intersecting intervals, then print gives additional line of extracted breaks.

Value

ursa_colortable returns value of $colortable element if ursaRaster object.

ursa_colortable<- returns ursaRaster object with modified $colortable element.

Class of $colortable element is “ursaColorTable”. This is named character vector, where names are categories, and values are “#RRGGBB” or R color names.

Extract function [] for ursaColorTable object returns object of class ursaColorTable.

Extract function names for ursaColorTable object returns character vector (names of categories).

Replace function names<- for ursaColorTable object returns ursaColorTable with changed names of categories.

ursa_colorindex returns index (if presents) for ursaColorTable object.

ursa_color returns character vector of colors in hex format.

Color tables are written to ENVI header file.

Warning

If colors are specified as R color names, then slow down may appear.

Author(s)

Nikita Platonov [email protected]

See Also

colorize

Examples

session_grid(NULL)
print(methods(class="ursaColorTable"))

a <- pixelsize()
print(a)
b1 <- colorize(a,value=c(400,500,600,700),interval=FALSE)
b2 <- colorize(a,value=c(450,550,650)    ,interval=TRUE)
display(list(b1,b2))
print(is.ursa(a,"colortable"))
print(is.ursa(b1,"colortable"))
print(is.ursa(b2,"colortable"))
print(ursa_colortable(a))
print(ursa_colortable(b1))
print(ursa_colortable(b2))
ursa_colortable(b2) <- c("Low"="darkolivegreen1"
                        ,"Moderate"="darkolivegreen2"
                        ,"High"="darkolivegreen3"
                        ,"undefined"="darkolivegreen4")
print(ursa_colortable(b2))
names(ursa_colortable(b2))[4] <- "Polar"
print(ursa_colortable(b2))
display(b2)

lab <- sample(c("A","B","C"),9,replace=TRUE)
lab
ct <- ursa_color(lab)
names(ct) <- lab
ct

Description

Set of generic functions, implemented for objects of ursaRaster class.

Usage

## S3 method for class 'ursaRaster'
duplicated(x, incomparables = FALSE, MARGIN = 2, fromLast = FALSE, ...)

## S3 method for class 'ursaRaster'
diff(x, lag = 1, differences = 1, ...)

Arguments

Value

duplicated(): logical of length equal to number of bands.

diff(): ursaRaster object.

Author(s)

Nikita Platonov [email protected]

See Also

duplicated, diff,

Examples

a <- ursa_dummy(5)
a[3] <- a[2]
a
duplicated(a)
diff(a)

Description

Function compose_close does followed tasks: 1) completes all unfinsished actions before shutting down graphical device, 2) cuts extra margins, and 3) opens resulted PNG file in the associated viewer.

Usage

compose_close(...)

## non-public
.compose_close(kind = c("crop2", "crop", "nocrop"),
               border = 5, bpp = 0, execute = TRUE, verbose = FALSE)

Arguments

Details

The cut manipulations (crop="crop" or crop="crop2") are implemented using readPNG and writePNG functions of package png. These fuctions have limitations in the memory allocation.

Function compose_close clears all internal graphical options, specified during compose_open executing.

Some parameters are specified in compose_open: weather output PNG file will be removed after opening (logical delafter), or what is the time of waiting for file opening and next removing (numerical wait in seconds).

Value

Function returns NULL value.

Warning

Currenty, execute=TRUE is implemented for Windows platform only using construction ⁠R CMD open \emph{fileout}⁠.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
a <- ursa_dummy(nband=6,min=0,max=255,mul=1/4)

## exam 1
compose_open()
compose_close()

## exam 2
compose_open(a)
compose_close()

## exam 3
compose_open("rgb",fileout="tmp1")
compose_plot(a[1:3])
compose_close(execute=FALSE)
Sys.sleep(1)
a <- dir(pattern="tmp1.png")
print(a)
file.remove(a)

Description

compose_design prepares scheme for layout of images and color bars.

Usage

compose_design(...)

Arguments

Details

Function compose_design extracts and validates required arguments from a list of parameters (three-dots construct) and passes them to internal function .compose_design.

Argument legend is a list or coerced to a list. The length of this list is equal to number of color bars; each item describes certain color bar. This desctiption is a list again with two elements, which desribes the position of color bar in relation to main panels of images.

If argument legend is in interval 1L:4L then it is interpreted as argument side in functions axis, mtext. Argument side in function compose_design plays the same role. It is introduced for consistency with R graphic system.

In the one of example below (See Examples section) the layout with dimension of two rows by three columns is considered (layout=c(2,3)). The dimension of resulting layout matrix is c(7,9), where 7=2*2+3, and 9=3*2+3.

     [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9]
[1,]    0    0    0    0    0    0    0    0    0
[2,]    0    0    0    0    0    0    0    0    0
[3,]    0    0    1    0    2    0    3    0    0
[4,]    0    0    0    0    0    0    0    0    0
[5,]    0    0    4    0    5    0    6    0    0
[6,]    0    0    0    0    0    0    0    0    0
[7,]    0    0    0    0    0    0    0    0    0

The complicated color bar structure is specified via R's list function:

>   leg <- list("7"=list(row=1,col=0),"8"=list(2,"left")
+              ,"9"=list("full","right"),"10"=list("top","full")
+              ,"11"=list(99,1:2),"12"=list("bottom",3))
> str(leg)
 $ 7 :List of 2
  ..$ row: num 1
  ..$ col: num 0
 $ 8 :List of 2
  ..$ : num 2
  ..$ : chr "left"
 $ 9 :List of 2
  ..$ : chr "full"
  ..$ : chr "right"
 $ 10:List of 2
  ..$ : chr "top"
  ..$ : chr "full"
 $ 11:List of 2
  ..$ : num 99
  ..$ : int [1:2] 1 2
 $ 12:List of 2
  ..$ : chr "bottom"
  ..$ : num 3

Here, six color bars are specified. It is a list of six lists (sub-lists). First item of sub-list is row number, and the second one is column number. Integers can be replaces by character keywords.

For row-position, "top" means 0L (less than first row), "bottom" means large integer value (greater than last row, currently, 99L), "first" means 1L, "last" means number of last row (2L in this example), "full" means whole range from first to last rows (1L:2L in this example). Values "top" and "bottom" are used for horizontal color bars (last three sub-lists), and the rest for vertical color bars (first three sub-lists).

For column-position, "left" means 0L (less then first column), "bottom" means large integer value (greater than last column, currently, 99L), "first" means first column (1L), "last" means last column (3L in this example), "full" means whole range from first to last columns ((1L:3L in this example)). Values "left" and "right" are used for vertical color bars, and the rest are for horizontal ones.

The resulting layout is a sparse matrix with zero values for each even row and each column. These zeros plays role of white space between panels in the plotted layout. In our example, values 1L:6L are corresponded to six map panels, and values 7L:12L are corresponded to six narrow panels of color bars (legends).

     [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9]
[1,]    0    0   10    0   10    0   10    0    0
[2,]    0    0    0    0    0    0    0    0    0
[3,]    7    0    1    0    2    0    3    0    9
[4,]    0    0    0    0    0    0    0    0    0
[5,]    8    0    4    0    5    0    6    0    9
[6,]    0    0    0    0    0    0    0    0    0
[7,]    0    0   11    0   11    0   12    0    0

Value

It is a list of class ursaLayout.

The returned value is passed to function compose_open and further is kept in the options until calling of compose_close.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
a <- ursa_dummy(nband=5,min=1,max=200,mul=1/8)
b <- list(colorize(a[1:3],pal.rich=240,pal.rotate=0)
         ,colorize(sqrt(a[4:5]),pal.rich=-15,pal.rotate=0,stretch="equal"))

cl1 <- compose_design(layout=c(2,3),byrow=TRUE,legend=NULL)
print(cl1)
compose_open(cl1)
compose_close()

cl2 <- compose_design(layout=c(2,3),byrow=FALSE,legend="left")
print(cl2$layout)
compose_open(cl2)
compose_close()

cl3 <- compose_design(a,side=2)
print(cl3)
compose_open(cl3)
compose_close()

cl4 <- compose_design(b)
print(cl4)
 ## to avoid over-time during example check -- begin
   compose_open(cl4)
   compose_plot(b,decor=FALSE,las=2)
   compose_close("nocrop")
 ## to avoid over-time during example check -- end

cl5 <- compose_design(b,byrow=FALSE,skip=3
                     ,legend=list(list("full","left"),list(1:2,"right")))
compose_open(cl5)
compose_plot(b,decor=FALSE)
compose_close("nocrop")

leg <- list(list(1,0),list(2,"left")
           ,list("full","right"),list("top","full")
           ,list(99,1:2),list("bottom",3))
str(leg)
cl6 <- compose_design(layout=c(2,3),skip=NA,legend=leg)
print(cl6)
compose_open(cl6,scale=3,pointsize=16)
compose_close("nocrop")

cl7 <- compose_design(layout=matrix(c(1,1,3,2,2,0),nrow=2,byrow=TRUE))
print(cl7)
compose_open(cl7)
compose_close()

Description

compose_legend recognizes color tables and characters among arguments and passes them to suitable functions for plotting on margins outside of panel area.

Usage

compose_legend(...)

Arguments

Details

Named list in the first argument is allowed or named vectors are allowed if first argument is not a list. For legend_colorbar name of object can be used as an argument units.

This function is designed to make plot on moderate level of usage with the followed construction:

compose_open(...)
compose_panel(...)
compose_legend(...)
compose_close(...)

Function compose_panel returns list of color tables of plotted rasters, and followed sequence is available:

ct <- compose_panel(a)
compose_legend(ct) # or, if 'a' has color tables, then 'compose_legend(a)'

Value

NULL

Author(s)

Nikita Platonov [email protected]

See Also

legend_colorbar

legend_mtext

Examples

session_grid(NULL)
b <- lapply(as.list(ursa_dummy(2)),colorize)
cd <- compose_design(layout=c(1,2),legend=list(list(1,"left"),list(1,"right")
                                              ,list("top","full"),list("bottom",1)))
for (i in 1:4) {
   compose_open(cd,dev=i==1)
   ct <- compose_panel(b,decor=FALSE)
   if (i==2)
      compose_legend(ct)
   else if (i==3)
      compose_legend(ct[[1]],'Tomorrow'=b[[2]]
                    ,top="This is example of legend composition"
                    ,format(Sys.Date(),"(c) %Y"))
   else if (i==4)
      compose_legend(c(ct,"top","bottom"),units=c("left","right"))
   compose_close()
}

Description

compose_open create plot layout and open PNG graphic device.

Usage

compose_open(...)

Arguments

Details

Other usage of compose_open(...,dev=TRUE) is

   compose_open(...,dev=FALSE)
   compose_close()

The reason to use compose_design function before compose_open is to reduce number of arguments in the case of complicated layout matrix and non-standard settings.

compose_open passes arguments to png function.

If character values are specified for arguments width, height or scale, then layout development is oriented to produce PNG file, which will be used as a paper copy. Character values for width and height are in centimeters. Character value ⁠V⁠ or ⁠1:⁠⁠V⁠ of scale defines scale ⁠1/⁠⁠V⁠.

The Cairo device (device="cairo") is more quick on MS Windows computers. However Windows GDI may produce less depth of colors (even 8 BPP) in the case of no font antialiasing. Usage of Windows GDI (device="windows") is a way to produce illustations for scientific journals with strict requirements of mininal line width, font size, etc.

The PNG layout reserves extra margins for captions of color bars. These margins are filled by white spaces. The cropping of layout applies to created PNG file using read-write functions of package png. Only white ("white", "#FFFFFF") or transparent ("transparent") colors are regognized as white spaces. Therefore, specification of bg!="white" or bg!="transparent" breaks PNG image cropping.

It is noted that Cyrillics is supported on Windows GDI (device="windows") and is not supported on Cairo (device="cairo") types of PNG device on MS Windows platform.

Argument retina is ignored for leaflet-compatible tiling.

Value

Name of created PNG file.

If dev=TRUE then output on console is layout matrix.

The set of required parameters for plotting are kept until function compose_close call via options.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
b <- ursa_dummy(nband=4,min=0,max=50,mul=1/4,elements=16)
p <- list(colorize(b[1:2],pal.rich=240,pal.rotate=0)
         ,colorize(sqrt(b[3:4]),pal.rich=-15,pal.rotate=0,stretch="equal"))
p
 
## exam #01
compose_open(width=950,dpi=150,pointsize=16,legend=NULL,dev=TRUE)

## exam #02
compose_open(pointsize=8,dpi=150,scale="1:130000000")
compose_plot(colorize(b[1]),scalebar=TRUE,coast=FALSE)
compose_close()

## exam #03
cl <- compose_design(layout=c(2,4)
                    ,legend=list(list("top","full"),list("bottom",1:3)))
compose_open(cl,dev=TRUE)

## exam #04
cl <- compose_design(p,layout=c(2,3),skip=c(2,4,6))
compose_open(cl,dev=TRUE)

## exam #05
cl <- compose_design(p,side=3)
compose_open(cl,dev=FALSE,bg="transparent")
compose_close()

Description

compose_panel divides the multi-band raster image (brick) or layers of raster images (stack) on the sequence of single-band images and plots each image on the separate panel of layout. Panel plotting is finalized by adding of decoration (gridlines, coastline, annotation, scalebar).

Usage

compose_panel(..., silent = FALSE)

Arguments

Details

For each panel of layout the sequence of called functions is permanent:
panel_new - - > panel_raster - - > panel_coastline - - > panel_graticule - - > panel_annotation - -> panel_scalebar.

If this order is undesirable, then call these functions in the required sequence.

Value

NULL

Author(s)

Nikita Platonov [email protected]

See Also

compose_plot, compose_legend

panel_new, panel_raster, panel_coastline, panel_graticule, panel_annotation, panel_scalebar

Examples

session_grid(NULL)
a <- ursa_dummy(6)
b1 <- list(maxi=a[1:4]*1e2,mini=a[5:6]/1e2)
print(b1)
b2 <- lapply(b1,function(x) colorize(x,nbreak=ifelse(global_mean(x)<100,5,NA)))
compose_open(b2,byrow=FALSE
            ,legend=list(list("bottom",1:2),list("bottom",3),list("left")))
ct <- compose_panel(b2,scalebar=2,coastline=3:4,gridline=5:6,gridline.margin=5
                   ,annotation.text=as.character(seq(6)))
compose_legend(ct)
legend_mtext(as.expression(substitute(italic("Colorbars are on the bottom"))))
compose_close()

Description

compose_plot plots images (raster brick or raster stack) and corresponding color bars according to given rectangular layout.

Usage

compose_plot(...)

Arguments

Details

Function merges to functions. The first one plots image layout and returns list of color tables. The second one plots legend (colorbars) based on returned color tables. Simplified description is:

ct <- compose_panel(...)
compose_legend(ct,...)

These two functions are separated to allow use additional plotting on image panel after primary plot of raster and decorations before panel change or legend plot.

Value

This function returns NULL value.

Author(s)

Nikita Platonov [email protected]

See Also

compose_panel
compose_legend

Examples

session_grid(NULL)
a <- ursa_dummy(nband=6,min=0,max=255,mul=1/4)
if (example1 <- TRUE) {
   b1 <- ursa_brick(a)
  # b1 <- colorize(b1,stretch="positive",ramp=FALSE)
   compose_open(b1)
   compose_plot(b1,grid=FALSE,coast=FALSE,scale=FALSE,trim=1
               ,stretch="positive",ramp=!FALSE)
   compose_close()
}
if (example2 <- TRUE) {
   b2 <- ursa_stack(a)
   compose_open(b2)
   compose_plot(b2,grid=FALSE,coast=FALSE,labels=5,trim=2,las=0)
   compose_close()
}

Description

create_envi creates ENVI binary and header files on disk. ENVI binary file is filled by blank (zero) values.
create_gdal is just an entry for GDAL wrapper; currently via internal ENVI implementation.

Usage

create_gdal(x, ...)

create_envi(x, ...)

Arguments

Details

Prior ursa version < 3.10, create_gdal() used classes and methods from package rgdal. Currenty, alternatives are not found for complete replacement of rgdal. At the present, ENVI binary and header are created, firstly, and close() transforms to desired GDAL format, finally.

create_envi and create_gdal use parameters of grid (boundary box, cell size, projection) from reference object of class ursaRaster in argument x or calls session_grid. You may specify values of GDAL or ENVI binary file later using [<-. If x is object of class ursaRaster then metadata parameters (interleave, data type, ignore value, etc) are inherited.

Keywords:

• fname - character. File name for created GDAL or ENVI file.
  
  For create_envi only: If compress of connections is not specified then example for “fileout” file name:

  • "fileout" - If external 'gzip' is found then "fileout.envigz" is created else "fileout.envi"

  • "fileout.envi" - "fileout.envi" is created without any compression.

  • "fileout." - "fileout" is created without any compression.

  • "fileout.bin" - "fileout.bin" is created without any compression.

  • "fileout.img" - "fileout.img" is created without any compression.

  • "fileout.dat" - "fileout.dat" is created without any compression.

• driver - character. For create_gdal only. Which GDAL driver is used.

• layername - character of length>=1. Layernames (‘Band name’ in ENVI header file)

• bandname - character of length>=1. Layernames (‘Band name’ in ENVI header file)

• name - character of length>=1. Layernames (‘Band name’ in ENVI header file)

• nodata - integer or numeric. Value in GDAL or ENVI binary file, which is interpretted as NA in R

• ignore - integer or numeric. Value in GDAL or ENVI binary file, which is interpretted as NA in R

• ignorevalue - integer or numeric. Value in GDAL or ENVI binary file, which is interpretted as NA in R

• bg - integer or numeric. Value in GDAL or ENVI binary file, which is interpretted as NA in R

• connection - character. For create_envi only. connections for ENVI binary file.
  
  Valid values are:

  • "gz" - connection is "gzfile"

  • "bz" - connection is "bzfile"

  • "xz" - connection is "xzfile"

  • "file" - connection is "file"

• interleave - character. Interleave. Valid values are "bsq", "bil", "bip". For create_gdal and driver="GTiff" valid values are "bsq" and "bil".

• datatype - character or integer (numeric). Data type.
  
  Valid values are:

  • 1, "byte", "Byte", "UInt8" = Byte: 8-bit unsigned integer

  • 2, "integer", "Int16" = Integer: 16-bit signed integer

  • 3, "Int32" = Long: 32-bit signed integer

  • 4, "real", "float", "Float32" = Floating-point: 32-bit single-precision

  • 5, "Float64" = Double-precision: 64-bit double-precision floating-point

  • 11, "UInt8" = Byte: 8-bit signed integer. Not in specification. Only for use with this package.

  • 12, "UInt16" = Integer: 16-bit unsigned integer

  • 13, "UInt32" = Long: 32-bit unsigned integer

  Specification https://www.nv5geospatialsoftware.com/docs/ENVIHeaderFiles.html is used.

• byteorder - numeric (integer). Byte order.

• bands - numeric( integer). Number of bands/layers

• nband - numeric( integer). Number of bands/layers

• nlayer - numeric( integer). Number of bands/layers

• layers - numeric( integer). Number of bands/layers

• compress - integer (numeric) or logical. For create_envi only. Should ENVI binary file be compressed after closing connection.

• wkt - integer (numeric) or logical. Forced adding ‘coordinate system string’ to ENVI header file

• ext - character. For create_envi only. Extension of ENVI binary file. For extensions not in c("envi","bin","dat","img") list

If file name is unknown, then random file name is used with informing via message().

Value

Object of class ursaRaster with opened connection of GDAL or ENVI binary file.

Author(s)

Nikita Platonov [email protected]

See Also

ursa_new creates object of class ursaRaster in memory and allows to assign values at once.

Use session_grid to check or specify parameters of grid before calling create_envi.

Use [<- to assign values to ENVI binary file after calling create_envi.

Use close (or close_envi) to close connections.

Examples

session_grid(NULL)
a <- create_envi()
fname <- a$con$fname
dir(pattern=basename(envi_list(fname)))
close(a)
invisible(envi_remove(fname))

a <- create_envi("exam1",layername=paste("Band",1:5)
                ,ignorevalue=99,datatype="Int16",interleave="bil")
ursa_info(a)
print(a[])
close(a)
invisible(envi_remove("exam1"))

Description

cubehelix returns set of RGB colours, which are screen display of intensity images

Usage

cubehelix(n, value = numeric(), weak = NA, rich = NA, rotate = NA, hue = NA, gamma = 1,
          dark = NA, light = NA, bright = NA, inv = NA, verbose = NA)

Arguments

Details

This is modified source code of function cubeHelix() from package rje under GPL>=2 license.

The palette design is oriented that figures can be printed on white paper. Under this assumption, light color is for small values, and dark color is for big values. In some computer vision and GIS software black background is used, and in this case light color for big values, and dark color of small values looks more naturally. For some thematic maps big values are light, and small values are small (for example, sea ice concentration: open water is blue, close ice is white). RGB and Grayscale remote sensing and photo imagery use light colors for strong signal, and dark colors for weak signal.

Light background is default for figure (specified by argument background in function compose_open).

The palette divergency can be defined only if value is specified. If all values are positive, or all values are negative, then returned palette is not drivergent. For divergent palettes the helix sequence is continuous.

If dark and lihgt are unspecified, the color contrast bewteen dark and light drops on reducing number of colors in returned vector.

Value

Vector of RGB color specification.

Acknowledgements

Dave Green, Robin Evans

Author(s)

Dave Green

Robin Evans

Nikita Platonov [email protected]

References

Dave Green's ‘cubehelix’ colour scheme.

Green, D. A., 2011, ‘A colour scheme for the display of astronomical intensity images’, Bulletin of the Astronomical Society of India, 39, 289. http://astron-soc.in/bulletin/11June/289392011.pdf (pre-print at 'arxiv.org')

rje::cubeHelix(); rje at CRAN: https://CRAN.R-project.org/package=rje

Examples

session_grid(NULL)
set.seed(352)
session_grid(regrid(mul=1/16))
a <- ursa_dummy(3,min=0,max=255)
b4 <- b3 <- b2 <- b1 <- vector("list",length(a))
for (i in seq_along(b1)) {
   b1[[i]] <- colorize(a[i],pal=cubehelix(11,weak=45*i,rotate=+270),ncolor=11)
   b2[[i]] <- colorize(a[i],pal=cubehelix(11,weak=45*i,rotate=-270),ncolor=11)
   b3[[i]] <- colorize(a[i]-127,pal=cubehelix)
   hue <- sample(seq(2)-1,1)
   s <- ifelse(hue==0,NA,runif(1,min=91,max=223))
   b4[[i]] <- colorize(a[i]-127,pal=cubehelix,pal.hue=hue,pal.dark=s,pal.light=s)
}
display(c(b1,b2),layout=c(2,NA),decor=FALSE)
display(c(b3,b4),layout=c(2,NA),decor=FALSE)

Description

Retrieve the dimension of an object of class ursaRaster. The replacement function is dummy; it doesn't change raster dimension.

Usage

## S3 method for class 'ursaRaster'
dim(x)
## S3 replacement method for class 'ursaRaster'
dim(x) <- value

Arguments

Details

Use extract operator [] and combine function c to change third (e.g., temporal) dimension of raster.
Use regrid function to change grid parameters and to resize/resample raster into new grid.

Value

The 'Extract' function dim returns named integer vector of length three: 1) number of lines/rows, 2) number of samples/columns, 3) number of bands/channels/layers.
The 'Replacement' function dim<- returns ursaRaster object without changes.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
session_grid(regrid(mul=1/16))
a <- ursa_dummy(nband=3)
ursa_info(a)
print(dim(a))
dim(a) <- c(25,00,34)
print(dim(a))
b <- create_envi("tmp1",bandname=letters[1:5],compress=FALSE)
print(dim(b))
close(b)
envi_remove("tmp1")

Description

If raster's categories are integer or numeric, then raster values are restored from names of categories. Otherwise only category names are dropped.

Usage

discolor(obj, nodata = NA)

Arguments

Value

Object of class ursaRaster without color table.

Author(s)

Nikita Platonov [email protected]

Examples

session_grid(NULL)
a <- colorize(pixelsize(),ncolor=7)
print(ursa_colortable(a))
print(a)
b <- discolor(a)
print(ursa_colortable(b))
print(b)

Description

High-level function to create multi-panel layout of images and to display with decoration (gridlines, coastlines, scalebar, colorbars) in the PNG format. It is an aggregator of low-level functions for typical plotting.

Usage

display(obj, ...)

Arguments

Details

If argument obj is missing (e.g, calling display() without parameters) then plotting the sessional CRS with blank image.

If argument obj is list of ursaRaster objects (or object of class ursaStack) then display_stack is called.

If argument obj is object of class ursaRaster and has 3 or 4 bands and values in each band are integer and in interval between 0 and 255, then display_rgb is called.

If argument obj is object of class ursaRaster then firstly internal test is applied to detect either image's bands contains homogeneous information (raster brick) or heterogeneous information (raster stack). Then either display_brick or display_stack is called. This test is rough due to unknown data origin. It is supposed to adjust kind of plotting by means of direct specification of display_brick or display_stack.

Value

Returned value from either display_brick or display_stack or display_rgb functions.

Author(s)

Nikita Platonov [email protected]

See Also

display_brick, display_stack, display_rgb

R-styled plotting: plot, image

Examples

session_grid(NULL)
set.seed(500)
a.brick <- a.stack <- ursa_dummy(nband=3,min=0,max=255,mul=1/16)
a.stack[2] <- a.stack[2]/10
a.stack[3] <- sqrt(a.stack[3])
a.rgb <- as.integer(round(a.brick))
print(a.brick)
print(a.stack)
print(a.rgb)
display(a.brick,decor=FALSE)
display(a.stack,decor=FALSE)
display(a.rgb)

Description

Raster image is forced to be interpreted as homogenuous (having the same units). It implies creating multi-panel layout with multiple colorbars.

Usage

display_brick(obj, ...)
display_homo(obj, ...)

Arguments

Details

If argument obj is list of ursaRaster objects (or object of class ursaStack) then obj is coerced to class ursaRaster ('stack' is coerced to 'brick').

display_homo is a synonym to display_brick. It is introduced to emphasize the plotting of homogenous object.

Value

Function returns NULL value.

Author(s)

Nikita Platonov [email protected]

See Also

display, display_stack, display_rgb

Examples

session_grid(NULL)
a <- ursa_dummy(nband=3,min=0,max=250)
a[2] <- -a[1]
a[3] <- sqrt(a[1])
a2 <- ursa_stack(a) 
print(a2)
display(a2) # likely 'display_stack' will be called
display_brick(a2,stretch="eq",labels=c(-150,-100,0,10,12,20,100,150))

Description

Raster images are forced to be interpreted as color composition with 3 (RGB) or 4 (RGBA) channels. Values should be in the range between 0 and 255.

Usage

display_rgb(obj, ...)

Arguments

Details

If argument obj is list of ursaRaster objects (or object of class ursaStack) then obj is coerced to class ursaRaster ('stack' is coerced to 'brick').

Colorbar is not plotted.

By default, the created PNG has 24 bits per pixel. This is equal to parameter bpp=24 (compose_close). It is allow to specify other value, e.g., display_rgb(a,bpp=8).

By default, labels of gridlines are located in bottom and left sides of the panel with raster. This is equal to parameter margin=c(TRUE,TRUE,FALSE,FALSE) (panel_graticule). It is allow to specify other value, e.g., display_rgb(a,margin=T).

Currently, for color compositions the argument useRaster (panel_raster) is introduced to fix possible coordinate mismatch for Cairo-devices, but have never used.

Value

Function returns NULL value.

Author(s)

Nikita Platonov [email protected]

See Also

display, display_brick, display_stack

Examples

session_grid(NULL)
a <- ursa_dummy(nband=3)
display_rgb(a)

Description

Raster images are forced to be interpreted as heterogenuous (having the different units). It implies creating multi-panel layout with multiple colorbars.

Usage

display_stack(obj, ...)
display_hetero(obj, ...)

Arguments

Details