Test distance input

Tests if input that refers to a distance is of valid input.

  • is_dist(): Tests if input can be interpreted as a distance.

  • is_dist_si(): Tests if input can be interpreted as a distance in SI units.

  • is_dist_pixel(): Tests if input can be interpreted as a distance in pixel.

is_dist(input, error = FALSE)

is_dist_si(input, error = FALSE)

is_dist_pixel(input, error = FALSE)

Arguments

input

Character or numeric vector. Elements must match the requirements of the SPATA2 distance framework. See details for more information.

error

Logical. If TRUE and the input is invalid the function throws an error.

Value

Logical vector of the same length as input. If error is TRUE and one or more elements of the input values can not be interpreted approapriately the functions throws an error.

Details

Several functions in SPATA2 have arguments that take distance input. To specifically refer to a distance the unit must be specified. There are three ways to create valid input for these arguments.

1. In pixel:

There are two valid input options to specify the distance in pixel:

  • numeric: Single numeric values, e.g. arg_input <- c(2, 3.554, 69, 100.67). If no unit is specified the input will be interpreted as pixels.

  • character: Suffixed with 'px', e.g. arg_input <- c('2px', '3.554px', '69px', '100.67px')

Note: The unit pixel (px) is used for distances as well as for areas. If pixel refers to a distance the pixel side length is meant. If pixel refers to an area the number of pixels is meant.

2. According to the Systeme international d`unites (SI):

Specifying distances in SI units e.g. arg_input <- c('2mm', '4mm') etc. requires the input to be a character as the unit must be provided as suffix. Between the numeric value and the unit must be no empty space! Valid suffixes can be obtained using the function validUnitsOfLengthSI().

3. As vectors of class unit:

Behind the scenes SPATA2 works with the units package. Input is converted into vectors of class units. Therefore, input can be directly provided this way: arg_input <- units::set_unit(x = c(2,4), value = 'mm') Note that pixel is not a valid unit in the units package. If you want to specify the input in pixel you have to use input option 1. In pixel.

Examples


##### use numeric or character vectors

library(SPATA2)

# will return TRUE
is_dist(input = 200) # -> 200 pixel
is_dist(input = "20px") # > 20 pixel

is_dist(input = "40.5mm") # -> 40.5 mm

# will return FALSE
is_dist(input = "30.5 mm") # -> empty space between 30.5 and mm

is_dist(input = ".4mm") # -> must start with a number

##### use units package

library(units)

dist_input <- set_units(x = c(2, 3, 4.4), value = "mm")

is_dist(dist_input)