Add 3d_objects vignette

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: fasterRaster
 Type: Package
 Title: Faster Raster and Spatial Vector Processing Using 'GRASS GIS'
-Version: 8.4.0.3
-Date: 2024-12-09
+Version: 8.4.0.4
+Date: 2024-12-16
 Authors@R: 
 	c(
 		person(

NEWS.md

@@ -1,4 +1,7 @@
-# fasterRaster 8.4.0.3 (2024-12-XX)
+# fasterRaster 8.4.0.4 (2024-12-XX)
+o Added vignette "3-dimensional objects".  
+
+# fasterRaster 8.4.0.3 (2024-12-15)
 
 ### Bug and issue fixes
 o Many minor fixes for CRAN submission!  

R/fasterRaster.r

@@ -314,7 +314,8 @@
 #' * Comparisons between `GRegion`s can be performed using the `==` and `!=` operators.
 #' * Vignette on **GRASS** "projects/locations" and "mapsets": `vignette("projects_mapsets", package = "fasterRaster")`
 #' * Vignette on **GRASS** "regions": `vignette("regions", package = "fasterRaster")`
-#' * Vignette on **fasteRaster** hidden functions: `vignette("hidden_functions", package = "fasterRaster")`
+#' * Vignette on **GRASS** 3-dimensional `GRaster`s and `GVector`s: `vignette("3d_objects", package = "fasterRaster")`
+#' * Vignette on **fasterRaster** hidden functions: `vignette("hidden_functions", package = "fasterRaster")`
 #'
 #' ## Classes
 #' * [`GLocation`]: Fundamental class; points to a "location/project" in **GRASS**

_pkgdown.yml

@@ -20,6 +20,7 @@ articles:
   - GRasters
   - faster_fasterRaster
   - addons
+  - 3d_objects
 
 - title: For Developers
   desc: Vignettes for developers

inst/pkgdown.yml

@@ -2,14 +2,15 @@ pandoc: 3.1.11
 pkgdown: 2.1.1
 pkgdown_sha: ~
 articles:
+  3d_objects: 3d_objects.html
   addons: addons.html
   faster_fasterRaster: faster_fasterRaster.html
   fasterRaster: fasterRaster.html
   GRasters: GRasters.html
   hidden_functions: hidden_functions.html
   projects_mapsets: projects_mapsets.html
   regions: regions.html
-last_built: 2024-12-10T18:32Z
+last_built: 2024-12-16T19:32Z
 urls:
   reference: https://github.com/adamlilith/fasterRaster/reference
   article: https://github.com/adamlilith/fasterRaster/articles

vignettes/3d_objects.Rmd

@@ -0,0 +1,41 @@
+---
+title: "3-dimensional objects"
+output: rmarkdown::html_vignette
+author: "Adam B. Smith"
+date: "`r Sys.Date()`"
+vignette: >
+  %\VignetteIndexEntry{3-dimensional objects}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+fig.path = 'man/figures/'
+```
+**fasterRaster** has limited support for 3-dimensional `GRaster`s and `GVector`s. A `GRaster` is like a multi-layered raster, except that layers contain values in "voxels" (3-dimensional pixels), where each layer has a z-resolution, in addition to its normal x- and y-resolutions. These layers are called "depths". A 3-dimensional vector has a z-dimension, so any point (i.e., an actual point, or points that together define a line or polygon) has a third dimension. You can test if an object is 3-dimensional using `topology()`, `is.2d()`, or `is.3d()`, or by looking at its metadata (i.e., just enter the name of the object in **R** and look at what is displayed).
+
+Thus far, *no functions that handle 3-dimensional `GRaster`s or `GVector`s have been tested.* Some functions like `spatSample()` have arguments that allow you to do something with a z-component. Also, some of the "getter" functions can report information about the third dimension of a `GRaster` or `GVector`.
+
+Three-dimensional `GRaster`s and `GVector`s should (?... remember, no testing yet!) work with most functions. In some cases, the third dimension will be ignored or removed. You should get a warning in these cases.
+
+## **fasterRaster** functions that specifically work with 3-dimensional objects
+
+   | **Function**              | **Object type**          |
+   | --------------------------|------------------------- |
+   | `bottom()`                | `GRaster` or `GVector`   |
+   | `dim3d()`                 | `GRaster`                |
+   | `is.2d()`                 | `GRaster` or `GVector`   |
+   | `is.3d()`                 | `GRaster` or `GVector`   |
+   | `ncell3d()`               | `GRaster`                |
+   | `ndepth()`                | `GRaster`                |
+   | `res3d()`                 | `GRaster`                |
+   | `top()`                   | `GRaster` or `GVector`   |
+   | `topology()`              | `GRaster` or `GVector`   |
+   | `zext()`                  | `GRaster` or `GVector`   |
+   | `zres()`                  | `GRaster`                |
+
+~ FINIS ~