Skip to content

Latest commit

 

History

History
147 lines (104 loc) · 4.42 KB

Readme.md

File metadata and controls

147 lines (104 loc) · 4.42 KB
Raw

CRAN Downloads R-CMD-check Project Status: Active – The project has reached a stable, usable state and is being actively developed.

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.

Installation

The package is on CRAN. The easiest way to download is via:

install.packages("qoi")

You can install the development version from GitHub with the following command:

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:

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.

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. The results from readPNG() are numerical values between 0 and 1. To compare the results multiply with 255 and change the mode to integer.

qoi_logo_rgb_png <- png::readPNG(system.file("extdata", "qoi_logo.png", package="qoi"))*255L

qoi_logo_rgb_qoi <- qoi::readQOI(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.

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:

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.

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/…: