Support reversal of colours

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: spatstat.geom
-Version: 3.3-4.005
-Date: 2024-11-29
+Version: 3.3-4.006
+Date: 2024-12-02
 Title: Geometrical Functionality of the 'spatstat' Family 
 Authors@R: c(person("Adrian", "Baddeley", 
                     role = c("aut", "cre", "cph"),

NAMESPACE

@@ -893,6 +893,7 @@ export("reset.spatstat.options")
 export("resolve.stringsAsFactors")
 export("restrict.colourmap")
 export("restrict.mask")
+export("rev.colourmap")
 export("reversePolyclipArgs")
 export("rexplode")
 export("rexplode.ppp")
@@ -1615,6 +1616,7 @@ S3method("rescale", "distfun")
  S3method("rescale", "ppp")
  S3method("rescale", "psp")
   S3method("rescale", "unitname")
+  S3method("rev", "colourmap")
 S3method("rexplode", "ppp")
 S3method("rjitter", "ppp")
 S3method("rotate", "diagramobj")

NEWS

@@ -1,4 +1,4 @@
-        CHANGES IN spatstat.geom VERSION 3.3-4.005
+        CHANGES IN spatstat.geom VERSION 3.3-4.006
 
 OVERVIEW
 
@@ -10,13 +10,22 @@ OVERVIEW
 
     o Bug fix
 
+NEW FUNCTIONS
+
+    o rev.colourmap
+    Reverses the sequence of colour values in a colour map.
+    A method for the generic 'rev'.
+
 SIGNIFICANT USER-VISIBLE CHANGES
 
     o plot.im
     New argument 'drop.ribbon' determines whether a ribbon will be displayed
     in the case where the pixel values are all equal.
     Default behaviour has changed.
 
+    o plot.im
+    New argument 'reverse.col' allows the sequence of colours to be reversed.
+
     o plot.imlist, image.imlist, image.listof
     If equal.ribbon=TRUE and equal.scales=TRUE, the colour ribbon
     is now neatly aligned with the plotted images.

R/colourtables.R

@@ -3,7 +3,7 @@
 #
 # support for colour maps and other lookup tables
 #
-# $Revision: 1.62 $ $Date: 2024/11/29 07:41:16 $
+# $Revision: 1.63 $ $Date: 2024/12/02 01:41:18 $
 #
 
 colourmap <- function(col, ..., range=NULL, breaks=NULL, inputs=NULL, gamma=1) {
@@ -631,6 +631,11 @@ colouroutputs <- function(x) {
   return(x)
 }
 
+rev.colourmap <- function(x) {
+  colouroutputs(x) <- rev(colouroutputs(x))
+  return(x)
+}
+
 restrict.colourmap <- function(x, ..., range=NULL, breaks=NULL, inputs=NULL) {
   stopifnot(inherits(x, "colourmap"))
   given <- c(!is.null(range), !is.null(breaks), !is.null(inputs))

R/plot.im.R

@@ -1,7 +1,7 @@
 #
 #   plot.im.R
 #
-#  $Revision: 1.159 $   $Date: 2024/11/21 07:44:45 $
+#  $Revision: 1.160 $   $Date: 2024/12/02 01:46:13 $
 #
 #  Plotting code for pixel images
 #
@@ -243,7 +243,8 @@ plot.im <- local({
   PlotIm <- function(x, ...,
                      main, 
                      add=FALSE, clipwin=NULL,
-                     col=NULL, valuesAreColours=NULL, log=FALSE,
+                     col=NULL, reverse.col=FALSE,
+                     valuesAreColours=NULL, log=FALSE,
                      ncolours=256, gamma=1, 
                      ribbon=show.all, show.all=!add,
                      drop.ribbon=FALSE,
@@ -558,6 +559,11 @@ plot.im <- local({
       ## transform to grey scale
       colourinfo$col <- to.grey(colourinfo$col)
     }
+
+    if(isTRUE(reverse.col) && !valuesAreColours) {
+      ## reverse the colour sequence (using rev.colourmap or rev.default)
+      colourinfo$col <- rev(colourinfo$col)
+    }
 
     # colour map to be returned (invisibly)
     i.col <- colourinfo$col

inst/doc/packagesizes.txt

@@ -29,4 +29,4 @@ date version nhelpfiles nobjects ndatasets Rlines srclines
 "2024-07-05" "3.3-0" 442 1186 0 35638 15596
 "2024-07-09" "3.3-2" 442 1186 0 35638 15596
 "2024-09-18" "3.3-3" 443 1187 0 35818 15596
-"2024-11-29" "3.3-4.005" 444 1190 0 36123 15596
+"2024-12-02" "3.3-4.006" 445 1191 0 36134 15596

inst/info/packagesizes.txt

@@ -29,4 +29,4 @@ date version nhelpfiles nobjects ndatasets Rlines srclines
 "2024-07-05" "3.3-0" 442 1186 0 35638 15596
 "2024-07-09" "3.3-2" 442 1186 0 35638 15596
 "2024-09-18" "3.3-3" 443 1187 0 35818 15596
-"2024-11-29" "3.3-4.005" 444 1190 0 36123 15596
+"2024-12-02" "3.3-4.006" 445 1191 0 36134 15596

man/colourmap.Rd

@@ -109,7 +109,8 @@ colourmap(col, \dots, range=NULL, breaks=NULL, inputs=NULL, gamma=1)
   To extract or replace all colour values, see
   \code{\link{colouroutputs}}.
 
-  See also \code{\link{restrict.colourmap}}.
+  See also \code{\link{restrict.colourmap}}
+  and \code{\link{rev.colourmap}}.
 
   See \code{\link[spatstat.geom:colourtools]{colourtools}}
   for more tools to manipulate colour values.

man/plot.im.Rd

@@ -9,7 +9,8 @@
   \method{plot}{im}(x, \dots,
                    main,
                    add=FALSE, clipwin=NULL,
-                   col=NULL, valuesAreColours=NULL, log=FALSE,
+                   col=NULL, reverse.col=FALSE,
+                   valuesAreColours=NULL, log=FALSE,
                    ncolours=256, gamma=1, 
                    ribbon=show.all, show.all=!add,
                    drop.ribbon=FALSE,
@@ -23,7 +24,8 @@
   \method{image}{im}(x, \dots,
                    main,
                    add=FALSE, clipwin=NULL,
-                   col=NULL, valuesAreColours=NULL, log=FALSE, 
+                   col=NULL, reverse.col=FALSE,
+                   valuesAreColours=NULL, log=FALSE, 
                    ncolours=256, gamma=1, 
                    ribbon=show.all, show.all=!add,
                    drop.ribbon=FALSE,
@@ -59,6 +61,10 @@
     an object of class \code{\link{colourmap}},
     or a \code{function} as described under Details.
   }
+  \item{reverse.col}{
+    Logical value. If \code{TRUE}, the sequence of colour values
+    specified by \code{col} will be reversed.
+  }
   \item{valuesAreColours}{
     Logical value. If \code{TRUE}, the pixel values of \code{x}
     are to be interpreted as colour values.
@@ -310,6 +316,9 @@
   
   If \code{spatstat.options("monochrome")} has been set to \code{TRUE}
   then \bold{all colours will be converted to grey scale values}.
+
+  If \code{reverse.col=TRUE}, the sequence of colour values specified
+  by \code{col} will be reversed (unless \code{valuesAreColours=TRUE}).
   
   Other graphical parameters controlling the display of both the pixel image
   and the ribbon can be passed through the \code{...} arguments

man/rev.colourmap.Rd

@@ -0,0 +1,43 @@
+\name{rev.colourmap}
+\alias{rev.colourmap}
+\title{
+  Reverse the Colours in a Colour Map
+}
+\description{
+  Reverse the sequence of colour values in a colour map.
+}
+\usage{
+  \method{rev}{colourmap}(x)
+}
+\arguments{
+  \item{x}{
+    A colour map (object of class \code{"colourmap"}).
+  }
+}
+\details{
+  This is a method for the generic \code{\link[base]{rev}}
+  for the class of colour maps.
+
+  The sequence of colour values in the colour map will be reversed,
+  without changing any other details. 
+}
+\value{
+  A colour map (object of class \code{"colourmap"}).
+}
+\author{
+  \spatstatAuthors.
+}
+\seealso{
+  \code{\link{colourmap}},
+  \code{\link{colouroutputs}}
+}
+\examples{
+  co <- colourmap(rainbow(100), range=c(-1,1))
+  opa <- par(mfrow=c(1,2))
+  plot(co, vertical=TRUE)
+  plot(rev(co), vertical=TRUE)
+  par(opa)
+}
+\keyword{spatial}
+\keyword{color}
+