Init

DESCRIPTION

@@ -0,0 +1,16 @@
+Package: qoi
+Type: Package
+Title: Read And Write QOI Images
+Version: 0.0.1
+Authors@R: person("Johannes", "Friedrich", role = c("aut", "cre"), email = "[email protected]")
+Maintainer: Johannes Friedrich <[email protected]>
+URL: https://github.com/JohannesFriedrich/qoi4R
+BugReports: https://github.com/JohannesFriedrich/qoi4R/issues
+Description: This package provides an easy and simple way to read, write and display bitmap images stored in the QOI (Quite Ok Image) format. It can read and write both files and in-memory raw vectors.
+License: GPL (>= 3)
+Encoding: UTF-8
+NeedsCompilation: yes
+RoxygenNote: 7.1.2
+Depends: 
+ R (>= 2.10)
+LazyData: true

NAMESPACE

@@ -0,0 +1,5 @@
+# Generated by roxygen2: do not edit by hand
+
+export(readQOI)
+export(writeQOI)
+useDynLib(qoi, .registration=TRUE)

NEWS.md

@@ -0,0 +1,3 @@
+# qoi 0.0.1
+
+ * Initial version

R/qoi-package.R

@@ -0,0 +1,10 @@
+#' @useDynLib qoi, .registration=TRUE
+NULL
+
+#' RGBA values for the Rlogo (https://www.r-project.org/logo/)
+#'
+#' @format [matrix] with 561 x 724 x 4 elements
+#' @docType data
+#' @author Johannes Friedrich
+#' @name Rlogo_RGBA
+NULL

R/readQOI.R

@@ -0,0 +1,21 @@
+#' Read an QOI image into a RGB(A) raster array
+#' @param qoi_image_path [character] (**required**): Path to a stored qoi-image
+#' @return A matrix with integer (0-255) RGB(A) values with dimensions height x width x channels.
+#' Until now 3 (RGB) and 4 (RGBA) channels are integrated in the specification.
+#' If the decoding went wrong the returned value is NULL.
+#' @author Johannes Friedrich
+#' @examples
+#' ## (1) Read RGBA values from file
+#' path <- system.file("extdata", "Rlogo.qoi", package="qoi")
+#' rlogo_qoi <- readQOI(path)
+#' dim(rlogo_qoi)
+#'
+#' ## (2) plot them
+#' plot.new()
+# rasterImage(rlogo_qoi/255, xleft = 0, xright = 1,
+# ytop = 0, ybottom = 1, interpolate = FALSE)
+#' @md
+#' @export
+readQOI <- function(qoi_image_path) {
+ .Call(qoiRead_, if(is.raw(qoi_image_path)) qoi_image_path else path.expand(qoi_image_path))
+}

R/writeQOI.R

@@ -0,0 +1,23 @@
+#' Write an QOI image from an RGB(A) raster array or matrix
+#' @param image [matrix] (**required**): Image represented by a integer matrix or array with values in the range of 0 to 255.
+#' @param target [character] or [connections] or [raw]: Either name of the file to write, a binary connection or a raw vector (raw() - the default - is good enough) indicating that the output should be a raw vector.
+#' @return The result is either stored in a file (if target is a file name), in a raw vector (if target is a raw vector) or sent to a binary connection.
+#' @author Johannes Friedrich
+#' @examples
+#' ## (1) Write to raw() -> see bytes
+#' bin <- writeQOI(Rlogo_RGBA)
+#' rawToChar(head(bin)) ## qoif
+#'
+#' \dontrun{
+#' ## (2) Write to a *.qoi file
+#' writeQOI(Rlogo_RGBA, "Rlogo_RGBA.qoi")
+#' }
+#' @md
+#' @export
+writeQOI <- function(image, target = raw()) {
+ if (inherits(target, "connection")) {
+ r <- .Call(qoiWrite_, image, raw())
+ writeBin(r, target)
+ invisible(NULL)
+ } else invisible(.Call(qoiWrite_, image, if (is.raw(target)) target else path.expand(target)))
+}

Readme.Rmd

@@ -0,0 +1,123 @@
+---
+output: rmarkdown::github_document
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+# QOI
+
+QOI is fast. It losslessy compresses images to a similar size of PNG, while offering 20x-50x faster encoding and 3x-4x faster decoding.
+
+QOI is simple. The reference en-/decoder fits in about 300 lines of C. The file format specification is a single page PDF.
+
+https://qoiformat.org/
+
+This **R**-package is a wrapper to handle QOI files with **R**.
+The package is completely written in base R with no dependencies and pure C-code.
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+
+```{r setup, include=FALSE, echo = FALSE}
+knitr::opts_chunk$set(collapse = TRUE,
+ comment = "##",
+ fig.retina = 2,
+ fig.align = "center",
+ fig.path = "README_figs/README-")
+Sys.setlocale("LC_TIME", "C")
+```
+
+## Installation
+
+Until now the package is not on CRAN, so just install it via GitHub:
+
+You can install the development version from GitHub with the following command:
+
+```{r, eval = FALSE}
+if (!require("devtools"))
+ install.packages("devtools")
+devtools::install_github("JohannesFriedrich/qoi4R")
+```
+
+
+## Usage
+
+There are just two main functions: `readQOI()` and `writeQOI()`.
+* `readQOI()`: Takes an qoi-format image and decodes it into its RGB or RGBA values. The result is a matrix with dimensions height x width x channels.
+* `writeQOI()`: Takes an RGB(A) matrix and encodes it into an qoi-image.
+
+### `readQOI()`
+
+Let´s read in an QOI-image delivered with this package:
+
+```{r}
+library(qoi)
+path <- system.file("extdata", "Rlogo.qoi", package="qoi")
+
+Rlogo_pixels <- readQOI(path)
+```
+
+The dimension of `Rlogo_pixels` is `r dim(Rlogo_pixels)`. So the height of the image is `r dim(Rlogo_pixels)[1]` px, the width `r dim(Rlogo_pixels)[2]` px and it has `r dim(Rlogo_pixels)[3]` channels, so it´s RGBA. With `3` channels it would be RGB encoded.
+
+With `readQOI()` is it possible to show the image with **R**.
+
+```{r}
+plot.new()
+rasterImage(Rlogo_pixels/255, xleft = 0, xright = 1,
+ ytop = 0, ybottom = 1, interpolate = FALSE)
+```
+
+The pixels returned from `readQOI()` are integer values between 0 - 255. To show them with `rasteImage()` it is necessary to divide them by 255 to get values between 0-1.
+
+Let´s compare the result to the wonderful [PNG-package](https://cran.r-project.org/web/packages/png).
+The results from `readPNG()` are numerical values between 0 and 1. To compare the results multiply with 255 and change the mode to integer.
+
+```{r}
+qoi_logo_rgb_png <- png::readPNG(path <- system.file("extdata", "qoi_logo.png", package="qoi"))*255
+
+qoi_logo_rgb_qoi <- qoi::readQOI(path <- system.file("extdata", "qoi_logo.qoi", package="qoi"))
+
+mode(qoi_logo_rgb_png) <- "integer"
+
+identical(qoi_logo_rgb_png, qoi_logo_rgb_qoi)
+```
+
+### `writeQOI()`
+
+With this function it is possible to save an RGB(A) matrix to an QOI-image.
+The input arguments are:
+* image: a matrix with dimensions height x width x channels
+* target: Either name of the file to write, a binary connection or a raw vector indicating that the output should be a raw vector (so the hex-interpretation of the image).
+
+If no second argument is given, the returned value is the hex-interpretation of the image in the QOI-file format.
+
+```{r}
+qoi_logo <- writeQOI(qoi_logo_rgb_qoi)
+rawToChar(head(qoi_logo))
+```
+
+
+If an second argument is given as character the image is saved to this name:
+
+```{r, eval = FALSE}
+writeQOI(qoi_logo_rgb_qoi, "qoi_logo_rgb.qoi")
+```
+
+If the second argument is of type `connection` the hex interpretation of the QOI-image will be send to this connection.
+
+```{r, eval = FALSE}
+file <- file("file.qoi", "wb")
+writeQOI(qoi_logo_rgb_qoi, file)
+close(file)
+```
+
+## Acknowlegment 
+
+This package would not exist without the following persons/homepages/tutorial/...:
+
+* [Phoboslab - original specification](https://github.com/phoboslab/qoi)
+* [PNG R-package](https://github.com/s-u/png)
+* [Example C-code R-package](https://github.com/coolbutuseless/simplecall)
+* [R extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html)
+* [Hadley´s R-Internals](https://github.com/hadley/r-internals)

Readme.md

@@ -0,0 +1,118 @@
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+# QOI
+
+QOI is fast. It losslessy compresses images to a similar size of PNG,
+while offering 20x-50x faster encoding and 3x-4x faster decoding.
+
+QOI is simple. The reference en-/decoder fits in about 300 lines of C.
+The file format specification is a single page PDF.
+
+<https://qoiformat.org/>
+
+This **R**-package is a wrapper to handle QOI files with **R**. The
+package is completely written in base R with no dependencies and pure
+C-code.
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+## Installation
+
+Until now the package is not on CRAN, so just install it via GitHub:
+
+You can install the development version from GitHub with the following
+command:
+
+``` r
+if (!require("devtools"))
+ install.packages("devtools")
+devtools::install_github("JohannesFriedrich/qoi4R")
+```
+
+## Usage
+
+There are just two main functions: `readQOI()` and `writeQOI()`. \*
+`readQOI()`: Takes an qoi-format image and decodes it into its RGB or
+RGBA values. The result is a matrix with dimensions height x width x
+channels. \* `writeQOI()`: Takes an RGB(A) matrix and encodes it into an
+qoi-image.
+
+### `readQOI()`
+
+Let´s read in an QOI-image delivered with this package:
+
+``` r
+library(qoi)
+path <- system.file("extdata", "Rlogo.qoi", package="qoi")
+
+Rlogo_pixels <- readQOI(path)
+```
+
+The dimension of `Rlogo_pixels` is 561, 724, 4. So the height of the
+image is 561 px, the width 724 px and it has 4 channels, so it´s RGBA.
+With `3` channels it would be RGB encoded.
+
+With `readQOI()` is it possible to show the image with **R**.
+
+``` r
+plot.new()
+rasterImage(Rlogo_pixels/255, xleft = 0, xright = 1,
+ ytop = 0, ybottom = 1, interpolate = FALSE)
+```
+
+<img src="README_figs/README-unnamed-chunk-3-1.png" width="672" style="display: block; margin: auto;" />
+
+The pixels returned from `readQOI()` are integer values between 0 - 255.
+To show them with `rasteImage()` it is necessary to divide them by 255
+to get values between 0-1.
+
+Let´s compare the result to the wonderful
+[PNG-package](https://cran.r-project.org/web/packages/png). The results
+from `readPNG()` are numerical values between 0 and 1. To compare the
+results multiply with 255 and change the mode to integer.
+
+``` r
+qoi_logo_rgb_png <- png::readPNG(path <- system.file("extdata", "qoi_logo.png", package="qoi"))*255
+
+qoi_logo_rgb_qoi <- qoi::readQOI(path <- system.file("extdata", "qoi_logo.qoi", package="qoi"))
+
+mode(qoi_logo_rgb_png) <- "integer"
+
+identical(qoi_logo_rgb_png, qoi_logo_rgb_qoi)
+## [1] TRUE
+```
+
+### `writeQOI()`
+
+With this function it is possible to save an RGB(A) matrix to an
+QOI-image. The input arguments are: \* image: a matrix with dimensions
+height x width x channels \* target: Either name of the file to write, a
+binary connection or a raw vector indicating that the output should be a
+raw vector (so the hex-interpretation of the image).
+
+If no second argument is given, the returned value is the
+hex-interpretation of the image in the QOI-file format.
+
+``` r
+qoi_logo <- writeQOI(qoi_logo_rgb_qoi)
+rawToChar(head(qoi_logo))
+## [1] "qoif"
+```
+
+If an second argument is given as character the image is saved to this
+name:
+
+``` r
+writeQOI(qoi_logo_rgb_qoi, "qoi_logo_rgb.qoi")
+```
+
+If the second argument is of type `connection` the hex interpretation of
+the QOI-image will be send to this connection.
+
+``` r
+file <- file("file.qoi", "wb")
+writeQOI(qoi_logo_rgb_qoi, file)
+close(file)
+```