Skip to content

Commit 923e792

Browse files
johnnychen94johnnychen94
committed
doc: add usage notes on FileIO and advanced tricks
1 parent 5b8f8a4 commit 923e792

File tree

2 files changed

+113
-33
lines changed

2 files changed

+113
-33
lines changed

‎README.md

Lines changed: 58 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,36 @@
66
[![Coverage](https://codecov.io/gh/johnnychen94/JpegTurbo.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/johnnychen94/JpegTurbo.jl)
77

88
JpegTurbo.jl is a Julia wrapper of the C library [libjpeg-turbo] that provides IO support for
9-
the JPEG image format.
9+
the JPEG image format. This package also backs the JPEG IO part of [ImageIO] and [FileIO].
1010

11-
The main functionality of this package consist of two functions: `jpeg_encode` and `jpeg_decode`.
12-
Check the [function references](https://johnnychen94.github.io/JpegTurbo.jl/dev/reference) for more
13-
details.
11+
For benchmark results against other image IO backends, please check
12+
[here](https://github.com/johnnychen94/JpegTurbo.jl/issues/15).
1413

15-
## API
14+
## Usage
15+
16+
There are two different usages for this package:
17+
18+
- (convenient) via the [FileIO]: `save`/`load`
19+
- (powerful) via the JpegTurbo.jl interfaces: `jpeg_encode`/`jpeg_decode`
20+
21+
### FileIO interface: `save`/`load`
22+
23+
[FileIO] is an IO frontend with various IO backends; [ImageIO] is the default IO backend provided
24+
by the JuliaImages ecosystem. When JpegTurbo (and/or ImageIO) are available in `DEPOT_PATH`, FileIO
25+
will uses JpegTurbo to load and save the JPEG images:
26+
27+
```julia
28+
using FileIO
29+
img = rand(64, 64)
30+
save("test.jpg", img)
31+
load("test.jpg")
32+
```
33+
34+
Note that you do not necessarily need to install them in your project environments. For instance,
35+
you can do `(@v1.8) pkg> add JpegTurbo` or `(@v1.8) pkg> add ImageIO` and it should work for your
36+
local setup.
37+
38+
### JpegTurbo interface: `jpeg_encode`/`jpeg_decode`
1639

1740
`jpeg_encode` is used to compress 2D colorant matrix as JPEG image.
1841

@@ -30,20 +53,38 @@ jpeg_decode([T,] io::IO; kwargs...) -> Matrix{T}
3053
jpeg_decode([T,] data::Vector{UInt8}; kwargs...) -> Matrix{T}
3154
```
3255

33-
## Feature set
56+
### Advanced: in-memory encode/decode
57+
58+
For some applications, it can be faster to do encoding/decoding without the need
59+
to read/write disk:
3460

35-
| function | filename | IOStream | in-memory buffer | pre-allocated output | multi-threads |
36-
| -------------------- | -------- | -------- | -------------------- | ------------------- | ------------- |
37-
| `jpeg_encode` | x | x | x | | x |
38-
| `jpeg_decode` | x | x | x | | x |
39-
| `ImageMagick.save` | x | x | x | | x |
40-
| `ImageMagick.load` | x | x | x | | x |
41-
| `QuartzImageIO.save` | x | x | x (`FileIO.Stream`) | | x |
42-
| `QuartzImageIO.load` | x | x | x (`FileIO.Stream`) | | x |
61+
```julia
62+
using JpegTurbo
63+
img = rand(64, 64)
64+
bytes = jpeg_encode(img) # Vector{UInt8}
65+
img_saveload = jpeg_decode(bytes) # size: 64x64
66+
```
4367

44-
Notes:
68+
### Advanced: preview optimization
4569

46-
- `x`: supported
47-
- empty: missing/unsupported yet
70+
One can request a single-component output or a downsampled output so that fewer calculation is
71+
needed during the decompression. This can be particularly useful to accelerate image preview.
72+
73+
```julia
74+
using BenchmarkTools, TestImages, JpegTurbo
75+
filename = testimage("earth", download_only=true)
76+
# full decompression
77+
@btime jpeg_decode(filename); # 224.760 ms (7 allocations: 51.54 MiB)
78+
# only decompress luminance component
79+
@btime jpeg_decode(Gray, filename); # 91.157 ms (6 allocations: 17.18 MiB)
80+
# process only a few pixels
81+
@btime jpeg_decode(filename; scale_ratio=0.25); # 77.254 ms (8 allocations: 3.23 MiB)
82+
# process only a few pixels for luminance component
83+
@btime jpeg_decode(Gray, filename; scale_ratio=0.25); # 63.119 ms (6 allocations: 1.08 MiB)
84+
```
4885

4986
[libjpeg-turbo]: https://github.com/libjpeg-turbo/libjpeg-turbo
87+
[FileIO]: https://github.com/JuliaIO/FileIO.jl
88+
[ImageIO]: https://github.com/JuliaIO/ImageIO.jl
89+
[Images.jl]: https://github.com/JuliaImages/Images.jl
90+
[JuliaImages]: https://juliaimages.org/

‎docs/src/index.md

Lines changed: 55 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,38 @@
22

33
[JpegTurbo.jl](https://github.com/johnnychen94/JpegTurbo.jl) is a Julia wrapper of the C library
44
[libjpeg-turbo](https://github.com/libjpeg-turbo/libjpeg-turbo) that provides IO support for the
5-
JPEG image format.
5+
JPEG image format. This package also backs the JPEG IO part of
6+
[ImageIO](https://github.com/JuliaIO/ImageIO.jl) and [FileIO](https://github.com/JuliaIO/FileIO.jl).
67

7-
The main functionality of this package consist of two functions: `jpeg_encode` and `jpeg_decode`.
8-
Check the [function references](@Function-references) for more details.
8+
For benchmark results against other image IO backends, please check
9+
[here](https://github.com/johnnychen94/JpegTurbo.jl/issues/15).
910

10-
## API
11+
## Usage
12+
13+
There are two different usages for this package:
14+
15+
- (convenient) via the [FileIO](https://github.com/JuliaIO/FileIO.jl): `save`/`load`
16+
- (powerful) via the JpegTurbo.jl interfaces: `jpeg_encode`/`jpeg_decode`
17+
18+
### FileIO interface: `save`/`load`
19+
20+
[FileIO](https://github.com/JuliaIO/FileIO.jl) is an IO frontend with various IO backends;
21+
[ImageIO](https://github.com/JuliaIO/ImageIO.jl) is the default IO backend provided by the
22+
JuliaImages ecosystem. When JpegTurbo (and/or ImageIO) are available in `DEPOT_PATH`, FileIO will
23+
uses JpegTurbo to load and save the JPEG images:
24+
25+
```julia
26+
using FileIO
27+
img = rand(64, 64)
28+
save("test.jpg", img)
29+
load("test.jpg")
30+
```
31+
32+
Note that you do not necessarily need to install them in your project environments. For instance,
33+
you can do `(@v1.8) pkg> add JpegTurbo` or `(@v1.8) pkg> add ImageIO` and it should work for your
34+
local setup.
35+
36+
### JpegTurbo interface: `jpeg_encode`/`jpeg_decode`
1137

1238
`jpeg_encode` is used to compress 2D colorant matrix as JPEG image.
1339

@@ -25,19 +51,32 @@ jpeg_decode([T,] io::IO; kwargs...) -> Matrix{T}
2551
jpeg_decode([T,] data::Vector{UInt8}; kwargs...) -> Matrix{T}
2652
```
2753

28-
## Feature set
54+
### Advanced: in-memory encode/decode
2955

30-
| function | filename | IOStream | in-memory buffer | pre-allocated output | multi-threads |
31-
| -------------------- | -------- | -------- | -------------------- | ------------------- | ------------- |
32-
| `jpeg_encode` | x | x | x | | x |
33-
| `jpeg_decode` | x | x | x | | x |
34-
| `ImageMagick.save` | x | x | x | | x |
35-
| `ImageMagick.load` | x | x | x | | x |
36-
| `QuartzImageIO.save` | x | x | x (`FileIO.Stream`) | | x |
37-
| `QuartzImageIO.load` | x | x | x (`FileIO.Stream`) | | x |
56+
For some applications, it can be faster to do encoding/decoding without the need
57+
to read/write disk:
3858

39-
Notes:
59+
```julia
60+
using JpegTurbo
61+
img = rand(64, 64)
62+
bytes = jpeg_encode(img) # Vector{UInt8}
63+
img_saveload = jpeg_decode(bytes) # size: 64x64
64+
```
4065

41-
- `x`: supported
42-
- empty: missing/unsupported yet
66+
### Advanced: preview optimization
4367

68+
One can request a single-component output or a downsampled output so that fewer calculation is
69+
needed during the decompression. This can be particularly useful to accelerate image preview.
70+
71+
```julia
72+
using BenchmarkTools, TestImages, JpegTurbo
73+
filename = testimage("earth", download_only=true)
74+
# full decompression
75+
@btime jpeg_decode(filename); # 224.760 ms (7 allocations: 51.54 MiB)
76+
# only decompress luminance component
77+
@btime jpeg_decode(Gray, filename); # 91.157 ms (6 allocations: 17.18 MiB)
78+
# process only a few pixels
79+
@btime jpeg_decode(filename; scale_ratio=0.25); # 77.254 ms (8 allocations: 3.23 MiB)
80+
# process only a few pixels for luminance component
81+
@btime jpeg_decode(Gray, filename; scale_ratio=0.25); # 63.119 ms (6 allocations: 1.08 MiB)
82+
```

0 commit comments

Comments
 (0)