Package 'isocubes'

Calculate voxel coordinates from a matrix where values in the matrix indicate height above the ground

Description

Calculate voxel coordinates from a matrix where values in the matrix indicate height above the ground

Usage

calc_heightmap_coords(
  mat,
  fill = NULL,
  scale = 1,
  flipx = FALSE,
  flipy = TRUE,
  ground = "xy",
  solid = TRUE,
  check_visibility = FALSE,
  verbose = FALSE
)

Arguments

mat	integer matrix. The matrix will be interpreted as cubes flat on the page, with the value in the matrix interpreted as the height above the page.
fill	matrix of colours the same dimensions as the mat argument. Default: NULL. If fill is not NULL, then a fill column will be included in the final returned coordinates.
scale	scale factor for values in matrix. Default = 1
flipx, flipy	Should the matrix be flipped in the horizontal/vertical directions (respectively)? Default: flipx = FALSE, flipy = TRUE. Note: flipy defaults to TRUE as matrices are indexed from the top-down, but the isometric coordinate space is increasing from the bottom up. Flipping the matrix vertically is usually what you want.
ground	Orientation of the ground plane. Default: 'xy'. Possible values 'xz', 'xy'
solid	Should the heightmap be made 'solid' i.e. without holes? default: TRUE. This can be an expensive operation in terms of both memory and CPU, but should be OK for simple examples. Set to FALSE if things take too long. This operation works by extruding cubes down from the top of the height map to the floor to ensure gaps do not appear when the slope is too great.
check_visibility	Should non-visible cubes be removed? Default: FALSE. If you plan on rotating or manipulating the returned coordinates then this should definitely by FALSE. If TRUE, then non-visible voxels will be entirely removed from the returned coordinates i.e. they will be missing if you change the rendering viewpoint from the default.
verbose	Be verbose? default: FALSE

Value

data.frame of voxel coordinates

Examples

# Plot the standard volcano 
mat <- volcano

# normalise height
mat <- mat - min(mat)

# Assign a distinct colour for each height value
val <- as.vector(mat)
val <- round(255 * val / max(val))
fill <- matrix("", nrow=nrow(mat), ncol=ncol(mat))
fill[] <- terrain.colors(256)[val + 1L]

# Calculate coordinates of heightmap, render as isocubes
coords <- calc_heightmap_coords(mat, fill = fill, scale = 0.3)
head(coords)
isocubesGrob(coords, size = 2, y = 0) |>
  grid::grid.draw()

---

Calculate indices of visible voxels when rendered from the specified view.

Description

Returned value is depth-sorted in back-to-front rendering order

Usage

calc_visibility(
  coords,
  xyplane = "flat",
  handedness = "right",
  value = "index",
  verbosity = 0,
  ...
)

Arguments

coords	data.frame of x,y,z coordinates for the cubes (integer coordinates)
xyplane	How is the xyplane oriented with respect to the unit isometric cube?. "left", "right", "flat" (or "top"). Default: "flat".
handedness	How is the z-axis positioned with respect to the xy-plane? I.e. is this a right-handed or left-handed coordinate system? Default: "right"
value	type of value to return. Default: 'index'. Valid values are 'index' and 'full'. If 'index', then returns an integer vector of which rows to render in back-to-front ordering. 'full' returns more information in a data.frame
verbosity	Verbosity level. Default: 0
...	other values passed to gpar() to set the graphical parameters e.g. lwd and col for the linewidth and colour of the outline stroke for each cube face.

Value

if value argument is 'index' then integer vector of visible vertices in back-to-front draw ordering. For value = 'full' return a data.frame with more complete information.

Examples

obj_sphere <- gen_sphere()
nrow(obj_sphere)
calc_visibility(obj_sphere) |>
   length()
   
calc_visibility(obj_sphere, value = 'full') |>
   head()

---

Align the object with the given coordinates

Description

Align the object with the given coordinates

Usage

coord_align(coords, loc = c(0, 0, 0), x = "mean", y = "mean", z = "mean")

Arguments

coords	data.frame with 'x', 'y' and 'z' coordinates
loc	location to align to. Default: c(0, 0, 0)
x, y, z	how to align the x coordinates to the given location. Default: 'mean'. Valid values 'min', 'mean', 'max', 'identity', 'median'

Value

data.frame of transformed coordinates

Examples

gen_sphere() |>
   coord_align(z = 'max', y = 'min') |>
   isocubesGrob(size = 3) |>
   grid::grid.draw()

---

Rotate object around a coordinate axis

Description

Rotate object around a coordinate axis

Usage

coord_rotate(coords, theta, axis = "z")

Arguments

coords	data.frame with 'x', 'y' and 'z' coordinates
theta	angle in radians.
axis	axis to rotate around. Default: 'z'. Valid values: 'x', 'y', 'z'

Value

data.frame of transformed coordinates

Examples

obj_letter |>
   coord_rotate(pi/2, 'y') |>
   isocubesGrob() |>
   grid::grid.draw()

---

Translate object

Description

Translate object

Usage

coord_translate(coords, x = 0, y = 0, z = 0)

Arguments

coords	data.frame with 'x', 'y' and 'z' coordinates
x, y, z	amount to translate along each axis. Default: 0

Value

data.frame of transformed coordinates

Examples

gen_sphere() |>
   coord_translate(x = 20, z = 40) |>
   isocubesGrob(size = 2) |>
   grid::grid.draw()

---

Generate voxel coordinates defined by an implicit function

Description

Generate voxel coordinates defined by an implicit function

Usage

gen_isosurface(
  f,
  upper = 0,
  lower = -Inf,
  scale = 1,
  nx = 51,
  ny = nx,
  nz = nx
)

Arguments

f	function of the form f(x, y, z) which returns a numeric value
lower, upper	When the supplied function is evaluated, the lower and upper limits define the range of values which will be considered to be inside the object. The efault [-Inf, 0] means that any value less than or equal to zero is inside, and all positive values are outside.
scale	extra scaling factor applied to coordinates before calling function
nx, ny, nz	the dimensions of the volume within which the function will be evaluated

Value

data.frame of coordinates

Examples

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Create a sphere of radius 10
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
coords <- gen_isosurface(
  f = function(x, y, z) {x^2 + y^2 + z^2},
  upper = 10^2
) 

coords |>
  isocubesGrob() |> 
  grid::grid.draw()
  
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Create a complex shape
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
grid::grid.newpage()
f <- function(x, y, z) {
  (x-2)^2 * (x+2)^2 + 
  (y-2)^2 * (y+2)^2 + 
  (z-2)^2 * (z+2)^2 +
  3 * (x^2 * y^2 + x^2 * z^2 + y^2 * z^2) +
  6 * x * y * z -
  10 * (x^2 + y^2 + z^2) + 22
}

gen_isosurface(
  f = f,
  scale = 0.1,
  nx = 70
) |> 
  isocubesGrob(size = 2) |> 
  grid::grid.draw()

---

Generate a rectangular prism centered at the origin

Description

To simplify implementation, only odd side lengths are generated.

Usage

gen_prism(x = 5, y = x, z = x)

Arguments

x, y, z

prism dimensions. Default 5x5x5. Note that due to the quantization of coordinates to integer values for rendering, this function rounds up even dimensions to the next odd number.

Value

data.frame of voxel coordinates

Examples

gen_prism(3, 5, 7) |>
   isocubesGrob() |>
   grid::grid.draw()

---

Generate voxel coordinates for a sphere centered at the origin

Description

Generate voxel coordinates for a sphere centered at the origin

Usage

gen_sphere(r = 10)

Arguments

r	radius. Default: 10

Value

data.frame of voxel coordinates

Examples

gen_sphere(1) |>
  isocubesGrob() |>
  grid::grid.draw()

---

Create a grob representing the specified axis orientation.

Description

The x, y and z axes are drawn in red, green and blue respectively.

Usage

isoaxesGrob(
  size = 5,
  x = 0.5,
  y = 0.5,
  default.units = "mm",
  xyplane = "flat",
  handedness = "right",
  labels = TRUE,
  verbosity = 0,
  ...
)

Arguments

size	length of each axis in default.units
x, y	the origin of the isometric coordinate system. If these values are given as vanilla floating point values, they will be interpreted as 'npc' units, otherwise a valid grid unit object must be supplied. By default the origin is the middle of the graphics device i.e. (x, y) = (0.5, 0.5)
default.units	Default unit for size of a cube is 'mm'
xyplane	How is the xyplane oriented with respect to the unit isometric cube?. "left", "right", "flat" (or "top"). Default: "flat".
handedness	How is the z-axis positioned with respect to the xy-plane? I.e. is this a right-handed or left-handed coordinate system? Default: "right"
labels	Include axis labels? Default: TRUE
verbosity	Verbosity level. Default: 0
...	other values passed to gpar() to set the graphical parameters e.g. lwd and col for the linewidth and colour of the outline stroke for each cube face.

Value

grid grob object

Examples

isoaxesGrob() |> 
  grid::grid.draw()

---

Create a grob of isocubes representing the voxels at the given coordiantes

Description

Create a grob of isocubes representing the voxels at the given coordiantes

Usage

isocubesGrob(
  coords,
  fill = NULL,
  fill_left = NULL,
  fill_right = NULL,
  intensity = c(1, 0.3, 0.7),
  size = 5,
  x = 0.5,
  y = 0.5,
  col = "black",
  default.units = "mm",
  xyplane = "flat",
  handedness = "right",
  verbosity = 0,
  ...
)

Arguments

coords	data.frame of x,y,z coordinates for the cubes (integer coordinates)
fill	fill colour for the top face of cube. Default: NULL will attempt to use the 'fill' colour in the coords data.frame, otherwise 'grey50'
fill_left, fill_right	fill colours for left and fight faces of cube.
intensity	c(1, 0.3, 0.6) Intensity shading for fill for the top, left and right faces respectively. Note: this setting has no effect on the shading of the left face if fill_left has been set explicitly by the user; same for the right face.
size	dimensions of cube i.e. the length of the vertical edge of the cube. Default: 5mm
x, y	the origin of the isometric coordinate system. If these values are given as vanilla floating point values, they will be interpreted as 'npc' units, otherwise a valid grid unit object must be supplied. By default the origin is the middle of the graphics device i.e. (x, y) = (0.5, 0.5)
col	Stroke colour for outline of cube faces. Default: black. If NA then no outlines will be drawn. If negative, then outline colour will be the same as the face colour.
default.units	Default unit for size of a cube is 'mm'
xyplane	How is the xyplane oriented with respect to the unit isometric cube?. "left", "right", "flat" (or "top"). Default: "flat".
handedness	How is the z-axis positioned with respect to the xy-plane? I.e. is this a right-handed or left-handed coordinate system? Default: "right"
verbosity	Verbosity level. Default: 0
...	other values passed to gpar() to set the graphical parameters e.g. lwd and col for the linewidth and colour of the outline stroke for each cube face.

Value

grid grob object

Examples

obj_sphere <- gen_sphere(r = 10)
fill <- rainbow(nrow(obj_sphere))
isocubesGrob(obj_sphere, fill = fill, size = 2) |>
  grid::grid.draw()

# The 'obj_organic' data.frame includes a 'fill' column which will be
# used by default
grid::grid.newpage()
isocubesGrob(obj_organic, size = 2) |>
  grid::grid.draw()

---

Create grob representing isometric grid of lines

Description

Create grob representing isometric grid of lines

Usage

isolinesGrob(
  N = 50,
  size = 5,
  x = 0.5,
  y = 0.5,
  col = "black",
  default.units = "mm",
  verbosity = 0,
  ...
)

Arguments

N	extents
size	dimensions of cube i.e. the length of the vertical edge of the cube. Default: 5mm
x, y	the origin of the isometric coordinate system. If these values are given as vanilla floating point values, they will be interpreted as 'npc' units, otherwise a valid grid unit object must be supplied. By default the origin is the middle of the graphics device i.e. (x, y) = (0.5, 0.5)
col	Stroke colour for outline of cube faces. Default: black. If NA then no outlines will be drawn. If negative, then outline colour will be the same as the face colour.
default.units	Default unit for size of a cube is 'mm'
verbosity	Verbosity level. Default: 0
...	other values passed to gpar() to set the graphical parameters e.g. lwd and col for the linewidth and colour of the outline stroke for each cube face.

Value

isometric line grid

Examples

isolinesGrob() |> 
  grid::grid.draw()

---

Create grob representing isometric grid of points

Description

Create grob representing isometric grid of points

Usage

isopointsGrob(
  N = 50,
  size = 5,
  x = 0.5,
  y = 0.5,
  col = "black",
  pch = ".",
  default.units = "mm",
  verbosity = 0,
  ...
)

Arguments

N	extents
size	dimensions of cube i.e. the length of the vertical edge of the cube. Default: 5mm
x, y	the origin of the isometric coordinate system. If these values are given as vanilla floating point values, they will be interpreted as 'npc' units, otherwise a valid grid unit object must be supplied. By default the origin is the middle of the graphics device i.e. (x, y) = (0.5, 0.5)
col	Stroke colour for outline of cube faces. Default: black. If NA then no outlines will be drawn. If negative, then outline colour will be the same as the face colour.
pch	plotting character. default '.'
default.units	Default unit for size of a cube is 'mm'
verbosity	Verbosity level. Default: 0
...	other values passed to gpar() to set the graphical parameters e.g. lwd and col for the linewidth and colour of the outline stroke for each cube face.

Value

isometric point grid

Examples

isopointsGrob(pch = '+') |> 
  grid::grid.draw()

---

Voxel coordinates for the letter R

Description

Voxel coordinates for the letter R

Usage

obj_letter

Format

An object of class data.frame with 68 rows and 3 columns.

See Also

Other datasets: obj_organic, obj_test

Examples

head(obj_letter)
isocubesGrob(obj_letter, size = 5, y = 0.05) |>
  grid::grid.draw()

---

Voxel coordinates for an organic shape

Description

Voxel coordinates for an organic shape

Usage

obj_organic

Format

An object of class tbl_df (inherits from tbl, data.frame) with 14292 rows and 4 columns.

See Also

Other datasets: obj_letter, obj_test

Examples

head(obj_organic)
cubes <- isocubesGrob(obj_organic, size = 2) |>
  grid::grid.draw()

---

Voxel coordinates for a test object useful for debugging orientation and visibility checks

Description

Voxel coordinates for a test object useful for debugging orientation and visibility checks

Usage

obj_test

Format

An object of class data.frame with 16 rows and 4 columns.

See Also

Other datasets: obj_letter, obj_organic

Examples

head(obj_test)
isocubesGrob(obj_test, size = 5, y = 0.05) |>
  grid::grid.draw()

---

Generate a random colour palette

Description

Generate a random colour palette

Usage

rand_palette(N = 256, seed = NULL)

Arguments

N	number of colors
seed	integer seed. Default: NULL

Value

character vector of colors

Examples

rand_palette(N = 20)

---