Improve plot_qsm() (issue #19), update documentation, and other sma…

…ll changes

NEWS.md

@@ -2,14 +2,15 @@
 
 ## New Features
 
--   `import_leaves()`: a new function to import leaves from [QSM-FaNNI](https://github.com/InverseTampere/qsm-fanni-matlab). The leaves are stored as an `rgl` `mesh3d()` object.
+-   `import_leaves()`: a new function to import leaves from [QSM-FaNNI](https://github.com/InverseTampere/qsm-fanni-matlab). The leaves are stored as an `rgl::mesh3d()` object.
 -   `export_mesh()`: The function now supports multiple 3d mesh formats including, `.ply`, `.obj` and `.stl`. It also supports exporting a QSM to [Blender](https://www.blender.org/) using the [QSM Blender Addons](https://github.com/InverseTampere/qsm-blender-addons) format `.txt`.
 -   New database called `twigs_index`. This is based on qualitative size classes supported by the literature, making it easier to select a twig radius for tree species without twig measurements. More info can be found in the `Twigs` vignette.
 -   `plot_qsm()`:
     -   Leaf meshes from `import_leaves()` or `aRchi::add_leaves()` can now be plotted with the `leaves` parameter. Leaf color and transparency can be controlled with `lf_color` and `lf_alpha` respectively.
-    -   Now accepts random color palettes for cylinders, points, or triangulation meshes by setting the `*_palette = "random"`. Additionally, the user can set a random color for each cylinder by setting `color` and `palette` to `"random"` at the same time.
+    -   Now accepts random color palettes for cylinders, points, or triangulation meshes by setting the `*_palette = "random"`. Additionally, the user can set a random color for each cylinder by setting both `color` and `palette` to `"random"`.
     -   Transparency options added for point clouds and main stem triangulation mesh with `pt_alpha` and `tri_alpha`.
-    -   Added an option to color the point cloud z-axis with a custom palette with `pt_palette`.
+    -   Point clouds can now be colored by any variable or palette using `pt_color` and `pt_palette`. The user can set a random color for each point by setting both `pt_color` and `pt_palette` to `random`.
+    -   Any `rgl::mesh3d()` objects can now be passed to `plot_qsm()` with the `mesh` parameter.
 -   `tree_metrics()`:
     -   `modified` is a standard output in the `tree` data frame. This is an average of the binary index of the cylinders modified by Real Twig. The `rTwig` version and run date are now also saved as `version` and `run_date`.
 
@@ -23,7 +24,7 @@
 
 -   `export_mesh()`: The function was entirely reworked using `Rcpp` for fast and efficient mesh export. All functionality that was dependent on `rgl` has been implemented in custom C++ functions.
 
--   unction names now use British English to be consistent with R standards. American spelling will still work interchangeably (e.g. `standardize_qsm()` vs `standardise_qsm()`.
+-   Function names now use British English to be consistent with R standards. American spelling will still work interchangeably (e.g. `standardize_qsm()` vs `standardise_qsm()`.
 
 -   Some functions have been renamed to follow tidy guidelines and have consistency within rTwig and other R packages (e.g. `qsm_summary()` -\> `summarise_qsm()`).
 
@@ -41,6 +42,8 @@
 
     -   Fixed an issue where disconnected data using `verify = FALSE` would fail crown base calculations due to missing branches (issue #18).
 
+-   `run_rtwig()`: The user can now use `standardize` and `standardise` interchangeably.
+
 -   Update `Twigs` vignette with new info and plots.
 
 ## Breaking Changes

R/box_dimension.R

@@ -2,10 +2,16 @@
 #'
 #' @description R port of Dominik Seidel's fractal analysis "box-dimension" metric.
 #'
-#' @param cloud A point cloud matrix size n x 3. Non-matrices are automatically converted to a matrix.
-#' @param lowercutoff The smallest box size determined by the point spacing of the cloud in meters. Defaults to 1 cm.
+#' @param cloud A point cloud matrix size n x 3.
+#'  Non-matrices are automatically converted to a matrix.
+#'
+#' @param lowercutoff The smallest box size determined by the point spacing of
+#'  the cloud in meters. Defaults to 1 cm.
+#'
 #' @param rm_int_box Remove the initial box as TRUE or FALSE. Defaults to FALSE.
-#' @param plot Plot the results. The user can specify "2D", "3D", or "ALL" plots. FALSE disables plotting. Defaults to FALSE.
+#'
+#' @param plot Plot the results. The user can specify "2D", "3D", or "ALL" plots.
+#'  FALSE disables plotting. Defaults to FALSE.
 #'
 #' @return Returns a list
 #' @export

R/cluster_cloud.R

@@ -1,15 +1,19 @@
 #' Cluster Cloud
 #'
 #' @description Cluster a point cloud or simulate a point cloud based on its QSM.
-#' If using the input point cloud, the cylinder ids are transferred to the
-#' cloud using the nearest neighbors. If simulating a cloud, the points are built
-#' directly from the cylinders with user controlled spacing. The cylinder id can
-#' be used to easily join the desired variables from the QSM to the cloud.
-#' The nearest neighbor search uses the C++ nanoflann library.
+#'  If using the input point cloud, the cylinder ids are transferred to the
+#'  cloud using the nearest neighbors. If simulating a cloud, the points are built
+#'  directly from the cylinders with user controlled spacing. The cylinder id can
+#'  be used to easily join the desired variables from the QSM to the cloud.
+#'  The nearest neighbor search uses the C++ nanoflann library.
 #'
 #' @param cylinder A QSM cylinder data frame.
-#' @param cloud The input point cloud for the QSM to cluster. If NULL (default), the simulated cloud is returned.
-#' @param spacing The point spacing in meters for the simulated cloud. Defaults to 0.02 meters.
+#'
+#' @param cloud The input point cloud for the QSM to cluster.
+#'  If NULL (default), the simulated cloud is returned.
+#'
+#' @param spacing The point spacing in meters for the simulated cloud.
+#'  Defaults to 0.02 meters.
 #'
 #' @return A point cloud data frame
 #' @export

R/correct_radii.R

@@ -4,7 +4,8 @@
 #'
 #' @param cylinder QSM cylinder data frame
 #' @param twig_radius Twig radius in millimeters
-#' @param broken_branch Enable or disable the broken branch filter. Defaults to enabled (TRUE).
+#' @param broken_branch Enable or disable the broken branch filter.
+#'  Defaults to enabled (TRUE).
 #'
 #' @return Returns a data frame
 #' @export

R/export_mat.R

@@ -1,6 +1,6 @@
 #' Export MAT
 #'
-#' @description Exports the cylinder data to be visualized with TreeQSM's `plot_cylinder_model()`.
+#' @description Exports the cylinder data to the format used by TreeQSM
 #'
 #' @param cylinder QSM cylinder data frame
 #' @param filename Desired name of file

R/export_mesh.R

@@ -2,15 +2,39 @@
 #'
 #' @description Exports a QSM cylinder mesh in various formats
 #'
-#' @param cylinder QSM cylinder data frame
-#' @param filename File name and path for exporting. The file extension is automatically added if not present.
-#' @param format Mesh file format. Defaults to "ply". Supported formats include "ply", "obj", "stl", and "blender". "blender" exports the mesh in the qsm-blender-addons format.
-#' @param radius Radius column name either quoted or unquoted. Defaults to modified cylinders from the cylinder data frame.
-#' @param color Optional cylinder color parameter used in the "ply" format. Colors are disabled by default. Colors must be a single hex color string, a `grDevices::colors()`, a vector of hex colors, or a quoted/unquoted column name. It can also be set to "random" to generate a random solid color, or FALSE to disable color on export. Vectors must have the same length as the cylinder data frame.
-#' @param palette Optional color palette for numerical data used in the "ply" format. Palettes include `colourvalues::color_palettes()` or a user supplied RGB palette matrix with the length of cylinder. It can also be set to "random" to generate a random palette.
-#' @param facets The number of facets in the polygon cross section. Defaults to 6, but can be increased to improve visual smoothness at the cost of performance and memory.
-#' @param normals Export surface normals on a per vertex basis. Defaults to FALSE, but can be set to TRUE.
-#' @param alpha Set the transparency of the cylinders used in the "ply" format. Defaults to 1. 1 is opaque and 0 is fully transparent.
+#' @param cylinder QSM cylinder data frame.
+#'
+#' @param filename File name and path for exporting.
+#'  The file extension is automatically added if not present.
+#'
+#' @param format Mesh file format. Defaults to `ply`.
+#'  Supported formats include `ply`, `obj`, `stl`, and `blender`.
+#'  `format = "blender"` exports the mesh in the qsm-blender-addons format.
+#'
+#' @param radius Radius column name either quoted or unquoted.
+#'  Defaults to the modified radii.
+#'
+#' @param color Optional cylinder color parameter.
+#'  `color` must be a single hex color string, a `grDevices::colors()`, a vector
+#'  of hex colors, or a quoted/unquoted column name.
+#'  Vectors must have the same length as the cylinder data frame.
+#'  `color = "random"` will generate a random color applied to all cylinders.
+#'  Defaults to branching order.
+#'
+#' @param palette Optional cylinder color palette for numerical data.
+#'  Palettes include `colourvalues::color_palettes()` or a user supplied RGB
+#'  palette matrix with the length of cylinder. It can also be set to "random"
+#'  to generate a random palette. If combined with `color = "random"`, each
+#'  cylinder will have a random, distinct color.
+#'
+#' @param facets The number of facets in the polygon cross section.
+#'  Defaults to 6. A higher number of facets improves visual smoothness at the
+#'  cost of plotting speed, performance and memory.
+#'
+#' @param normals Export surface normals per vertex. Defaults to FALSE.
+#'
+#' @param alpha Set the transparency of the cylinders used in the "ply" format.
+#'  Defaults to 1. 1 is opaque and 0 is fully transparent.
 #'
 #' @return A mesh file
 #' @export
@@ -313,7 +337,7 @@ format_mesh <- function(
       if (!is.null(color) && color == FALSE) {
         colors <- NULL
       } else {
-        colors <- plotting_colors(cylinder, color, palette, branch_order)
+        colors <- plot_colors(cylinder, color, palette, branch_order)
         colors <- rep(colors, each = facets * 6)
 
         if (!is.null(alpha)) {

R/import_leaves.R

@@ -1,12 +1,12 @@
 #' Import Leaves
 #'
 #' @description Imports leaves created by the QSM foliage and needles naive
-#' insertion (QSM-FaNNI) algorithm. The leaves are stored as a triangular mesh,
-#' compatible with both rTwig and RGL functions.
+#'  insertion (QSM-FaNNI) algorithm. The leaves are stored as a triangular mesh,
+#'  compatible with both rTwig and RGL functions.
 #'
 #' @param filename a QSM-FaNNI .obj file
 #' @param simplify simplify the mesh by removing duplicate vertices. This can
-#' reduce memory usage at the cost of import speed. Defaults to FALSE.
+#'  reduce memory usage at the cost of import speed. Defaults to FALSE.
 #'
 #' @return Returns an RGL mesh3d object
 #' @export

R/import_treeqsm.R

@@ -3,7 +3,8 @@
 #' @description Imports a QSM created by TreeQSM
 #'
 #' @param filename a TreeQSM .mat MATLAB file
-#' @param version TreeQSM version. Defaults to 2.x.x. The user can also specify the 2.0 format.
+#' @param version TreeQSM version. Valid versions include `2.3.0` - `2.4.1` and
+#'  `2.0`. Defaults to the most recent format of `2.x.x`.
 #'
 #' @return Returns a list
 #' @export