version 0.11.0

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: RNifti
-Version: 0.10.0
-Date: 2018-10-19
+Version: 0.11.0
+Date: 2019-06-17
 Title: Fast R and C++ Access to NIfTI Images
 Authors@R: c(person("Jon","Clayden",role=c("cre","aut"),email="code@clayden.org"),
              person("Bob","Cox",role="aut"),
@@ -23,9 +23,9 @@ License: GPL-2
 URL: https://github.com/jonclayden/RNifti
 BugReports: https://github.com/jonclayden/RNifti/issues
 Encoding: UTF-8
-RoxygenNote: 6.0.1
+RoxygenNote: 6.1.0
 NeedsCompilation: yes
-Packaged: 2018-10-19 14:04:33 UTC; jon
+Packaged: 2019-06-17 16:12:34 UTC; jon
 Author: Jon Clayden [cre, aut],
   Bob Cox [aut],
   Mark Jenkinson [aut],
@@ -36,4 +36,4 @@ Author: Jon Clayden [cre, aut],
   Mark Adler [cph]
 Maintainer: Jon Clayden <code@clayden.org>
 Repository: CRAN
-Date/Publication: 2018-10-19 14:50:02 UTC
+Date/Publication: 2019-06-17 17:33:52 UTC

NAMESPACE

@@ -2,6 +2,8 @@
 
 S3method("$",niftiImage)
 S3method("$<-",niftiImage)
+S3method("[",internalImage)
+S3method("[<-",internalImage)
 S3method("dim<-",internalImage)
 S3method("pixdim<-",default)
 S3method("pixunits<-",default)

NEWS

@@ -2,6 +2,33 @@ Significant changes to the RNifti package are laid out below for each release.
 
 ===============================================================================
 
+VERSION 0.11.0
+
+R interface
+
+- It is now possible to index directly into objects of class `internalImage`,
+  meaning that individual elements or arbitrary blocks may be converted to R
+  vectors or arrays, without needing to convert everything. This can save
+  significant amounts of memory for large images.
+
+API changes
+
+- This release introduces the `NiftiImageData` C++ class as the main way to
+  encapsulate the data in a NIfTI image. This class handles datatypes and data
+  scaling, and provides indexing, iterators and other niceties. The doxygen
+  documentation has full details.
+- As a result of this new introduction, the templated `getData()` method within
+  `NiftiImage` is deprecated in favour of `data()`, which returns a (constant
+  or mutable) object of class `NiftiImageData` rather than a standard `vector`.
+
+Bug fixes
+
+- The slope and intercept fields in `nifti` objects (from the `oro.nifti`
+  package) are now ignored, since that package does its own scaling. (Reported
+  by John Muschelli, issue #13.)
+
+===============================================================================
+
 VERSION 0.10.0
 
 R interface

R/image.R

@@ -7,9 +7,14 @@
 #' not be changed.
 #' 
 #' @param x An \code{"internalImage"} object.
-#' @param value Not used. Changing the dimensions of an internal image is
-#'   invalid, and will produce an error.
-#' @param ... Additional parameters to methods. Currently unused.
+#' @param value Not used. Changing the dimensions of (or data in) an internal
+#'   image is invalid, and will produce an error. Convert to an array first.
+#' @param i,j Index vectors. May be missing, which indicates that the whole of
+#'   the relevant dimension should be obtained.
+#' @param ... Additional parameters to methods. Only used for additional
+#'   indices.
+#' @param drop If \code{TRUE} (the default), unitary indices in the result will
+#'   be dropped. This mirrors the behaviour of standard array indexing.
 #' 
 #' @author Jon Clayden <code@@clayden.org>
 #' @aliases internalImage
@@ -34,6 +39,74 @@ as.array.internalImage <- function (x, ...)
     return (.Call("pointerToArray", x, PACKAGE="RNifti"))
 }
 
+#' @rdname internalImage
+#' @export
+"[.internalImage" <- function (x, i, j, ..., drop = TRUE)
+{
+    nArgs <- nargs() - as.integer(!missing(drop))
+    if (nArgs < 2)
+        return (as.array(x))
+
+    # Evaluate the indices, replacing missing values with -1
+    if (nArgs == 2)
+        indices <- substitute(list(i))
+    else
+        indices <- substitute(list(i,j,...))
+    present <- (sapply(indices, as.character)[-1] != "")
+    if (any(!present))
+        indices[which(!present)+1] <- -1
+    indices <- eval(indices, parent.frame())
+    lengths <- rep(-1L, nArgs - 1)
+    lengths[present] <- sapply(indices[present], length)
+
+    dims <- dim(x)
+    data <- NULL
+
+    if (all(lengths == -1))
+        return (as.array(x))
+    else if (any(lengths == 0))
+        return (numeric(0))
+    else if (nArgs == 2 && present[1])
+    {
+        if (is.matrix(i))
+        {
+            if (ncol(i) != length(dims))
+                stop("Index matrix should have as many columns as the image has dimensions")
+            strides <- c(1, cumprod(dims)[-length(dims)])
+            locs <- apply(i, 1, function(n) sum((n-1)*strides) + 1)
+        }
+        else
+            locs <- as.integer(i)
+
+        return (.Call("indexVector", x, locs, PACKAGE="RNifti"))
+    }
+    else if (nArgs != length(dims) + 1)
+        stop("Number of indices (", nArgs-1, ") not equal to the dimensionality of the image (", length(dims), ")")
+    else
+    {
+        data <- .Call("indexList", x, lapply(seq_along(indices), function(l) {
+            if (length(indices[[l]]) == 1 && indices[[l]] == -1)
+                seq_len(dims[l])
+            else if (is.logical(indices[[l]]))
+                which(indices[[l]])
+            else
+                indices[[l]]
+        }), PACKAGE="RNifti")
+        dim(data) <- ifelse(present, lengths, dims)
+    }
+
+    if (drop)
+        data <- drop(data)
+    return (data)
+}
+
+#' @rdname internalImage
+#' @export
+"[<-.internalImage" <- function (x, i, j, ..., value)
+{
+    stop("The data in an internal image cannot be changed - convert to array first")
+}
+
 #' @export
 print.niftiImage <- function (x, ...)
 {

README.md

@@ -195,7 +195,12 @@ This arrangement is efficient and generally works well, but many R operations st
 
 ## API
 
-It is possible to use the package's NIfTI-handling code in other R packages' compiled code, thereby obviating the need to duplicate the reference implementation. Moreover, `RNifti` provides a C++ wrapper class, `NiftiImage`, which simplifies memory management, supports the package's internal image pointers and persistence, and provides syntactic sugar. Full doxygen documentation for this class is available at <http://doxygen.flakery.org/RNifti/>, and is also provided with package releases.
+It is possible to use the package's NIfTI-handling code in other R packages' compiled code, thereby obviating the need to duplicate the reference implementation. Moreover, `RNifti` provides two key C++ wrapper classes:
+
+- `NiftiImage`, which simplifies memory management and supports the package's internal image pointers and associated reference counting, and
+- `NiftiImageData`, which encapsulates the pixel data within an image, and handles datatype multiplexing and data scaling, as well as providing indexing, iterators and other niceties.
+
+Full doxygen documentation for these classes is available at <http://doxygen.flakery.org/RNifti/>, and is also provided with package releases.
 
 A third-party package can use the `NiftiImage` class by including
 
@@ -254,7 +259,7 @@ Thanks to contributions from [@soolijoo](https://github.com/soolijoo), it is pos
 | `src/znzlib/znzlib.c`           | Source for I/O functions from the NIfTI-1 reference implementation                                  |
 | `src/zlib/*`                    | `zlib` source files for reading and writing gzipped files (optional, as above)                      |
 
-Note that the `NiftiImage` class is header-only, but C code from the NIfTI-1 reference implementation will need to be compiled and linked into the project. The `print.h` header should be included before including `NiftiImage.h`, so that the R API is not used for printing error messages. The [`standalone` directory](https://github.com/jonclayden/RNifti/tree/master/standalone) provides a minimal example.
+Note that the `NiftiImage` and `NiftiImageData` classes are header-only, but C code from the NIfTI-1 reference implementation will need to be compiled and linked into the project. The `NiftiImage_print.h` header should be included before including `NiftiImage.h`, so that the R API is not used for printing error messages. The [`standalone` directory](https://github.com/jonclayden/RNifti/tree/master/standalone) provides a minimal example.
 
 ## The NIfTI-2 format
 

inst/doxygen/html/annotated.html

@@ -1,9 +1,9 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
-<meta name="generator" content="Doxygen 1.8.14"/>
+<meta name="generator" content="Doxygen 1.8.15"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>RNifti: Class List</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
@@ -30,7 +30,7 @@
 </table>
 </div>
 <!-- end header part -->
-<!-- Generated by Doxygen 1.8.14 -->
+<!-- Generated by Doxygen 1.8.15 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 var searchBox = new SearchBox("searchBox", "search",false,'Search');
@@ -69,18 +69,21 @@
 <div class="textblock">Here are the classes, structs, unions and interfaces with brief descriptions:</div><div class="directory">
 <div class="levels">[detail level <span onclick="javascript:toggleLevel(1);">1</span><span onclick="javascript:toggleLevel(2);">2</span><span onclick="javascript:toggleLevel(3);">3</span>]</div><table class="directory">
 <tr id="row_0_" class="even"><td class="entry"><span style="width:0px;display:inline-block;">&#160;</span><span id="arr_0_" class="arrow" onclick="toggleFolder('0_')">&#9660;</span><span class="icona"><span class="icon">N</span></span><b>RNifti</b></td><td class="desc"></td></tr>
-<tr id="row_0_0_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span id="arr_0_0_" class="arrow" onclick="toggleFolder('0_0_')">&#9660;</span><span class="icona"><span class="icon">N</span></span><b>internal</b></td><td class="desc"></td></tr>
-<tr id="row_0_0_0_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="struct_r_nifti_1_1internal_1_1vec3.html" target="_self">vec3</a></td><td class="desc"></td></tr>
-<tr id="row_0_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span id="arr_0_1_" class="arrow" onclick="toggleFolder('0_1_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_r_nifti_1_1_nifti_image.html" target="_self">NiftiImage</a></td><td class="desc">Thin wrapper around a C-style <code>nifti_image</code> struct that allows C++-style destruction </td></tr>
-<tr id="row_0_1_0_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="struct_r_nifti_1_1_nifti_image_1_1_block.html" target="_self">Block</a></td><td class="desc">Inner class referring to a subset of an image </td></tr>
+<tr id="row_0_0_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span id="arr_0_0_" class="arrow" onclick="toggleFolder('0_0_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_r_nifti_1_1_nifti_image.html" target="_self">NiftiImage</a></td><td class="desc">Thin wrapper around a C-style <code>nifti_image</code> struct that allows C++-style destruction </td></tr>
+<tr id="row_0_0_0_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="struct_r_nifti_1_1_nifti_image_1_1_block.html" target="_self">Block</a></td><td class="desc">Inner class referring to a subset of an image </td></tr>
+<tr id="row_0_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span id="arr_0_1_" class="arrow" onclick="toggleFolder('0_1_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_r_nifti_1_1_nifti_image_data.html" target="_self">NiftiImageData</a></td><td class="desc">Wrapper class encapsulating a NIfTI data blob, with responsibility for handling data scaling and polymorphism </td></tr>
+<tr id="row_0_1_0_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="struct_r_nifti_1_1_nifti_image_data_1_1_concrete_type_handler.html" target="_self">ConcreteTypeHandler</a></td><td class="desc">Concrete inner class template defining behaviour specific to individual data types </td></tr>
+<tr id="row_0_1_1_"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="struct_r_nifti_1_1_nifti_image_data_1_1_element.html" target="_self">Element</a></td><td class="desc">Inner class representing a single element in the data blob </td></tr>
+<tr id="row_0_1_2_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_r_nifti_1_1_nifti_image_data_1_1_iterator.html" target="_self">Iterator</a></td><td class="desc"><a class="el" href="class_r_nifti_1_1_nifti_image_data_1_1_iterator.html" title="Iterator type for NiftiImageData, with Element as its value type.">Iterator</a> type for <code><a class="el" href="class_r_nifti_1_1_nifti_image_data.html" title="Wrapper class encapsulating a NIfTI data blob, with responsibility for handling data scaling and poly...">NiftiImageData</a></code>, with <code><a class="el" href="struct_r_nifti_1_1_nifti_image_data_1_1_element.html" title="Inner class representing a single element in the data blob.">Element</a></code> as its value type </td></tr>
+<tr id="row_0_1_3_"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="struct_r_nifti_1_1_nifti_image_data_1_1_type_handler.html" target="_self">TypeHandler</a></td><td class="desc">Abstract inner class defining the type-specific functions required in concrete subclasses </td></tr>
 </table>
 </div><!-- directory -->
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
 Generated by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
-</a> 1.8.14
+</a> 1.8.15
 </small></address>
 </body>
 </html>