version 0.7.0

DESCRIPTION

@@ -1,10 +1,11 @@
 Package: RNifti
-Version: 0.5.1
-Date: 2017-05-11
+Version: 0.7.0
+Date: 2017-06-11
 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"),
              person("Mark","Jenkinson",role="aut"),
+             person("Matt","Hall",role="ctb"),
              person("Rick","Reynolds",role="ctb"),
              person("Kate","Fissell",role="ctb"),
              person("Jean-loup","Gailly",role="cph"),
@@ -14,23 +15,24 @@ Suggests: testthat (>= 0.11.0)
 Enhances: oro.nifti, tractor.base
 LinkingTo: Rcpp
 Description: Provides very fast access to images stored in the NIfTI-1 file
-    format <http://nifti.nimh.nih.gov/nifti-1>, with seamless synchronisation
-    between compiled C and interpreted R code. Not to be confused with
-    'RNiftyReg', which provides tools for image registration.
+    format <http://www.nitrc.org/docman/view.php/26/64/nifti1.h>, with seamless
+    synchronisation between compiled C and interpreted R code. Not to be
+    confused with 'RNiftyReg', which provides tools for image registration.
 License: GPL-2
 URL: https://github.com/jonclayden/RNifti
 BugReports: https://github.com/jonclayden/RNifti/issues
 Encoding: UTF-8
-RoxygenNote: 5.0.1
+RoxygenNote: 6.0.1
 NeedsCompilation: yes
-Packaged: 2017-05-11 09:53:14 UTC; jon
+Packaged: 2017-06-11 16:32:21 UTC; jon
 Author: Jon Clayden [cre, aut],
   Bob Cox [aut],
   Mark Jenkinson [aut],
+  Matt Hall [ctb],
   Rick Reynolds [ctb],
   Kate Fissell [ctb],
   Jean-loup Gailly [cph],
   Mark Adler [cph]
 Maintainer: Jon Clayden <code@clayden.org>
 Repository: CRAN
-Date/Publication: 2017-05-11 12:47:29 UTC
+Date/Publication: 2017-06-12 04:45:26 UTC

NAMESPACE

@@ -9,12 +9,14 @@ S3method(pixdim,default)
 S3method(pixunits,default)
 S3method(print,niftiHeader)
 S3method(print,niftiImage)
+export("orientation<-")
 export("pixdim<-")
 export("pixunits<-")
 export("qform<-")
 export("sform<-")
 export(dumpNifti)
 export(ndim)
+export(orientation)
 export(origin)
 export(pixdim)
 export(pixunits)

NEWS

@@ -2,6 +2,30 @@ Significant changes to the RNifti package are laid out below for each release.
 
 ===============================================================================
 
+VERSION 0.7.0
+
+- The new orientation() function can be used to identify the approximate
+  storage orientation of an image. A replacement version allows the image
+  data and metadata dimensions to be permuted and/or reversed.
+- Image reorientation is similarly available through the C++ API.
+- The sform and qform replacement methods should now follow R's usual
+  semantics, and no longer modify the object in place if it is referred to by
+  more than one name.
+- The NiftiImage class is now suitable for use in standalone C++ projects.
+  (Thanks to Matt Hall.)
+
+===============================================================================
+
+VERSION 0.6.0
+
+- Slope and intercept values in a NIfTI-1 header are now applied to the image
+  data when converting it to an R array (which will in this case always be of
+  mode double), or a C++ vector.
+- The slope and intercept will be reset to zero when updating the data in an
+  internal image object.
+
+===============================================================================
+
 VERSION 0.5.1
 
 - A potential crash and/or memory leak in the C++ NiftiImage copy assignment

R/nifti.R

@@ -28,7 +28,7 @@
 #' 
 #' @author Jon Clayden <code@@clayden.org>
 #' @seealso \code{\link{writeNifti}}
-#' @references The NIfTI-1 standard (\url{http://nifti.nimh.nih.gov/nifti-1}).
+#' @references The NIfTI-1 standard (\url{http://www.nitrc.org/docman/view.php/26/64/nifti1.h}).
 #' @export
 readNifti <- function (file, internal = FALSE)
 {
@@ -63,7 +63,7 @@ readNifti <- function (file, internal = FALSE)
 #' 
 #' @author Jon Clayden <code@@clayden.org>
 #' @seealso \code{\link{readNifti}}, \code{\link{updateNifti}}
-#' @references The NIfTI-1 standard (\url{http://nifti.nimh.nih.gov/nifti-1}).
+#' @references The NIfTI-1 standard (\url{http://www.nitrc.org/docman/view.php/26/64/nifti1.h}).
 #' @export
 writeNifti <- function (image, file, template = NULL, datatype = "auto")
 {
@@ -137,7 +137,7 @@ updateNifti <- function (image, template = NULL)
 #' dumpNifti(array(0L, dim=c(10,10)))
 #' 
 #' @author Jon Clayden <code@@clayden.org>
-#' @references The NIfTI-1 standard (\url{http://nifti.nimh.nih.gov/nifti-1}).
+#' @references The NIfTI-1 standard (\url{http://www.nitrc.org/docman/view.php/26/64/nifti1.h}).
 #' @export
 dumpNifti <- function (image)
 {

R/xform.R

@@ -3,19 +3,24 @@
 #' These functions convert the ``qform'' or ``sform'' information in a NIfTI
 #' header to or from a corresponding affine matrix. These two ``xform''
 #' mechanisms are defined by the NIfTI standard, and may both be in use in a
-#' particular image header.
+#' particular image header. They define the relationship between the storage
+#' order of the image and real space.
 #' 
 #' @param image,x An image, in any acceptable form (see
 #'   \code{\link{retrieveNifti}}).
 #' @param useQuaternionFirst A single logical value. If \code{TRUE}, the
 #'   ``qform'' matrix will be used first, if it is defined; otherwise the
 #'   ``sform'' matrix will take priority.
-#' @param value A new 4x4 qform or sform matrix. If the matrix has a
-#'   \code{"code"} attribute, the appropriate qform or sform code is also set.
-#' @return A affine matrix corresponding to the ``qform'' or ``sform''
-#'   information in the image header. This is a plain matrix, which does not
-#'   have the \code{"affine"} class or \code{source} and \code{target}
-#'   attributes.
+#' @param value A new 4x4 qform or sform matrix, or orientation string. If a
+#'   matrix has a \code{"code"} attribute, the appropriate qform or sform code
+#'   is also set.
+#' @return For \code{xform}, an affine matrix corresponding to the ``qform''
+#'   or ``sform'' information in the image header. For \code{orientation}, a
+#'   string with three characters indicating the (approximate) orientation of
+#'   the image. Each character may be `R' for left-to-right, `L' for
+#'   right-to-left, `A' for posterior-to-anterior, `P' for
+#'   anterior-to-posterior, `S' for inferior-to-superior, or `I' for
+#'   superior-to-inferior. The replacement forms return the modified object.
 #' 
 #' @note The qform and sform replacement functions are for advanced users only.
 #'   Modifying the transforms without knowing what you're doing is usually
@@ -32,7 +37,7 @@
 #' xform(im)
 #' 
 #' @author Jon Clayden <code@@clayden.org>
-#' @references The NIfTI-1 standard (\url{http://nifti.nimh.nih.gov/nifti-1})
+#' @references The NIfTI-1 standard (\url{http://www.nitrc.org/docman/view.php/26/64/nifti1.h})
 #'   is the definitive reference on ``xform'' conventions.
 #' @export
 xform <- function (image, useQuaternionFirst = TRUE)
@@ -54,6 +59,20 @@ xform <- function (image, useQuaternionFirst = TRUE)
     return (.Call("setXform", x, value, FALSE, PACKAGE="RNifti"))
 }
 
+#' @rdname xform
+#' @export
+orientation <- function (x, useQuaternionFirst = TRUE)
+{
+    return (.Call("getOrientation", x, isTRUE(useQuaternionFirst), PACKAGE="RNifti"))
+}
+
+#' @rdname xform
+#' @export
+"orientation<-" <- function (x, value)
+{
+    return (.Call("setOrientation", x, as.character(value), PACKAGE="RNifti"))
+}
+
 #' Transform points between voxel and ``world'' coordinates
 #' 
 #' These functions are used to transform points from dimensionless pixel or

README.md

@@ -1,6 +1,6 @@
 # RNifti: Fast R and C++ Access to NIfTI Images
 
-The [NIfTI-1 format](http://nifti.nimh.nih.gov/nifti-1) is a popular file format for storing medical imaging data, widely used in medical research and related fields. Conceptually, a NIfTI-1 file incorporates multidimensional numeric data, like an R `array`, but with additional metadata describing the real-space resolution of the image, the physical orientation of the image, and how the image should be interpreted.
+The [NIfTI-1 format](http://www.nitrc.org/docman/view.php/26/64/nifti1.h) is a popular file format for storing medical imaging data, widely used in medical research and related fields. Conceptually, a NIfTI-1 file incorporates multidimensional numeric data, like an R `array`, but with additional metadata describing the real-space resolution of the image, the physical orientation of the image, and how the image should be interpreted.
 
 There are several packages available for reading and writing NIfTI-1 files in R, and these are summarised in the [Medical Imaging task view](https://cran.r-project.org/view=MedicalImaging). However, `RNifti` is distinguished by its
 
@@ -183,3 +183,19 @@ void myfunction (SEXP image_)
 (`RNifti` will also have to be added to the `Imports` list in the package's `DESCRIPTION` file, as well as `LinkingTo`.) The `RNiftiAPI.h` header should only be included once per package, since it contains function implementations. Multiple includes will lead to duplicate symbol warnings from your linker. Therefore, if multiple source files require access to the NIfTI-1 reference implementation, it is recommended that the API header be included alone in a separate ".c" or ".cpp" file, while others only include the main `RNifti.h`.
 
 `RNifti` is not specifically designed to be thread-safe, and R itself is expressly single-threaded. However, some effort has been made to try to minimise problems associated with parallelisation, such as putting R API calls within a critical region if OpenMP is being used. If you are using the API in a package that does use OpenMP or another form of threads, it is wise to preregister the functions exported by `RNifti` before use, by calling `niftilib_register_all()`. In single-threaded contexts this is optional, and will be performed when required.
+
+## Use in pure C++ projects
+
+Thanks to contributions from @soolijoo, it is possible (as of package version 0.7.0) to use the `NiftiImage` C++ class in standalone C++ projects. You will need the following files:
+
+| Path                            | Purpose                                                                                             |
+| ------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `inst/include/lib/*.h`          | Headers defining the `NiftiImage` class itself, related functions and macros                        |
+| `inst/include/niftilib/*.h`     | Headers for the NIfTI-1 reference implementation                                                    |
+| `inst/include/znzlib/znzlib.h`  | Header for I/O functions from the NIfTI-1 reference implementation                                  |
+| `inst/include/zlib/*.h`         | `zlib` headers for reading and writing gzipped files (optional; system `zlib` can be used instead)  |
+| `src/niftilib/nifti1_io.c`      | Source file for the NIfTI-1 reference implementation                                                |
+| `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 constant `_NO_R__` should be defined, and `print.h` included, before including `NiftiImage.h`, so that the R API is not used.

inst/doxygen/html/annotated.html

@@ -3,7 +3,7 @@
 <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.13"/>
+<meta name="generator" content="Doxygen 1.8.12"/>
 <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.13 -->
+<!-- Generated by Doxygen 1.8.12 -->
 <script type="text/javascript">
 var searchBox = new SearchBox("searchBox", "search",false,'Search');
 </script>
@@ -75,7 +75,7 @@
 <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.13
+</a> 1.8.12
 </small></address>
 </body>
 </html>