Document polarToCart and cartToPolar. Update NEWS.

NEWS.md

@@ -1,3 +1,20 @@
+# Rvision 0.6.3
+
+## New features
+
+* Some Hu moment invariants were missing. 
+* OpenCV DLLs are now copied from ROpenCVLite on installation on Windows. 
+* New functions to compute square root, logarithm, exponential, and powers. 
+* New function to compute Gabor kernels for image filtering. 
+* New function to convert vector fields to polar coordinates and back. 
+
+## Minor improvements and fixes
+
+* The documentation has been fixed/improved in several places.
+* Minor bug fixes here and there.
+
+---
+
 # Rvision 0.6.2
 
 ## New features

R/arithmetic.R

@@ -171,14 +171,63 @@ addWeighted <- function(e1, e2, weight = c(0.5, 0.5), target = "new") {
 }
 
 
+#' @title Convert Cartesian Coordinates to Polar
+#'
+#' @description \code{cartToPolar} converts the x and y coordinates of a vector
+#'  field (for instance, as generated by \code{\link{spatialGradient}}) and
+#'  computes their polar representation (magnitude and angle).
+#'
+#' @param x A 32- or 64-bit (32F or 64F) \code{\link{Image}} object
+#'  corresponding to the x coordinates of the vector field.
+#'
+#' @param y A 32- or 64-bit (32F or 64F) \code{\link{Image}} object
+#'  corresponding to the y coordinates of the vector field.
+#'
+#' @param magnitude The location where the magnitude should be stored. It can
+#'  take 2 values:
+#'  \itemize{
+#'   \item{"new":}{a new \code{\link{Image}} object is created and the results
+#'    are stored inside (the default).}
+#'   \item{An \code{\link{Image}} object:}{the results are stored in another
+#'    existing \code{\link{Image}} object. Note that an error will be thrown if
+#'    \code{magnitude} does not have the same dimensions, number of channels,
+#'    and bit depth as \code{x} and \code{y}.}
+#'  }
+#'
+#' @param angle The location where the angle should be stored. It can take 2
+#'  values:
+#'  \itemize{
+#'   \item{"new":}{a new \code{\link{Image}} object is created and the results
+#'    are stored inside (the default).}
+#'   \item{An \code{\link{Image}} object:}{the results are stored in another
+#'    existing \code{\link{Image}} object. Note that an error will be thrown if
+#'    \code{angle} does not have the same dimensions, number of channels,
+#'    and bit depth as \code{x} and \code{y}.}
+#'  }
+#'
+#' @param degree A logical indicating whether the angles are measured in radians
+#'  (the default) or degrees.
+#'
+#' @return If \code{magnitude="new"} and \code{angle="new"}, the function returns
+#'  a list containing two \code{\link{Image}} objects. If \code{magnitude} and
+#'  \code{angle} are \code{\link{Image}} objects, the function returns nothing
+#'  and modifies these \code{\link{Image}} objects in place.
+#'
+#' @author Simon Garnier, \email{garnier@@njit.edu}
+#'
+#' @seealso \code{\link{polarToCart}}, \code{\link{spatialGradient}}
+#'
+#' @examples
+#' balloon <- image(system.file("sample_img/balloon1.png", package = "Rvision"))
+#' field <- spatialGradient(balloon)
+#' lapply(field, changeBitDepth, bitdepth = "32F", target = "self")
+#' field_converted <- cartToPolar(field$dx, field$dy)
+#'
 #' @export
 cartToPolar <- function(x, y, magnitude = "new", angle = "new", degree = FALSE) {
   if (!isImage(x) | !isImage(y))
     stop("x and y must be Image objects.")
 
-  if (x$nchan() != 1 | y$nchan() != 1)
-    stop("x and y must be single-channel Image objects.")
-
   if (x$depth() != "32F" & x$depth() != "64F")
     stop("x must be a 32F or 64F image object.")
 
@@ -219,14 +268,63 @@ cartToPolar <- function(x, y, magnitude = "new", angle = "new", degree = FALSE)
 }
 
 
+#' @title Convert Polar Coordinates to Cartesian
+#'
+#' @description \code{polarToCart} calculates x and y coordinates of vector
+#'  field from their polar representation (magnitude and angle).
+#'
+#' @param magnitude A 32- or 64-bit (32F or 64F) \code{\link{Image}}
+#'  object corresponding to the magnitudes of the vector field.
+#'
+#' @param angle A 32- or 64-bit (32F or 64F) \code{\link{Image}}
+#'  object corresponding to the angles of the vector field.
+#'
+#' @param x The location where the x coordinates should be stored. It can take 2
+#'  values:
+#'  \itemize{
+#'   \item{"new":}{a new \code{\link{Image}} object is created and the results
+#'    are stored inside (the default).}
+#'   \item{An \code{\link{Image}} object:}{the results are stored in another
+#'    existing \code{\link{Image}} object. Note that an error will be thrown if
+#'    \code{x} does not have the same dimensions, number of channels, and bit
+#'    depth as \code{magnitude} and \code{angle}.}
+#'  }
+#'
+#' @param y The location where the y coordinates should be stored. It can take 2
+#'  values:
+#'  \itemize{
+#'   \item{"new":}{a new \code{\link{Image}} object is created and the results
+#'    are stored inside (the default).}
+#'   \item{An \code{\link{Image}} object:}{the results are stored in another
+#'    existing \code{\link{Image}} object. Note that an error will be thrown if
+#'    \code{y} does not have the same dimensions, number of channels, and bit
+#'    depth as \code{magnitude} and \code{angle}.}
+#'  }
+#'
+#' @param degree A logical indicating whether the angles are measured in radians
+#'  (the default) or degrees.
+#'
+#' @return If \code{x="new"} and \code{y="new"}, the function returns a list
+#'  containing two \code{\link{Image}} objects. If \code{x} and \code{y} are
+#'  \code{\link{Image}} objects, the function returns nothing and modifies these
+#'  \code{\link{Image}} objects in place.
+#'
+#' @author Simon Garnier, \email{garnier@@njit.edu}
+#'
+#' @seealso \code{\link{polarToCart}}, \code{\link{spatialGradient}}
+#'
+#' @examples
+#' balloon <- image(system.file("sample_img/balloon1.png", package = "Rvision"))
+#' field <- spatialGradient(balloon)
+#' lapply(field, changeBitDepth, bitdepth = "32F", target = "self")
+#' field_converted <- cartToPolar(field$dx, field$dy)
+#' field_deconverted <- polarToCart(field_converted$magnitude, field_converted$angle)
+#'
 #' @export
 polarToCart <- function(magnitude, angle, x = "new", y = "new", degree = FALSE) {
   if (!isImage(magnitude) | !isImage(angle))
     stop("magnitude and angle must be Image objects.")
 
-  if (magnitude$nchan() != 1 | angle$nchan() != 1)
-    stop("magnitude and angle must be single-channel Image objects.")
-
   if (magnitude$depth() != "32F" & magnitude$depth() != "64F")
     stop("magnitude must be a 32F or 64F image object.")
 

docs/pkgdown.yml

@@ -8,7 +8,7 @@ articles:
   z4_inplace: z4_inplace.html
   z5_gpu: z5_gpu.html
   z6_queue: z6_queue.html
-last_built: 2022-09-12T12:43Z
+last_built: 2022-09-12T13:43Z
 urls:
   reference: https://swarm-lab.github.io/ROpenCVLite/reference
   article: https://swarm-lab.github.io/ROpenCVLite/articles