-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathReadme.Rmd
163 lines (119 loc) · 4.98 KB
/
Readme.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
---
output: rmarkdown::github_document
editor_options:
markdown:
wrap: 72
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
<!-- badges: start -->
[](https://CRAN.R-project.org/package=qoi)
[](https://www.r-pkg.org/pkg/qoi)
[](https://github.com/JohannesFriedrich/qoi4R/actions/workflows/R-CMD-check.yaml)
[](http://www.repostatus.org/#active)
[](https://codecov.io/github/JohannesFriedrich/qoi4R)
<!-- badges: end -->
# 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
The package is on CRAN. The easiest way to download is via:
```{r, eval = FALSE}
install.packages("qoi")
```
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(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)
```
### `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)