Skip to content

Commit 413f5d1

Browse files
rNozrNoz
committed
docs: readmes, moduledocs and changelog
1 parent 2b1ec30 commit 413f5d1

File tree

3 files changed

+159
-102
lines changed

3 files changed

+159
-102
lines changed

‎CHANGELOG.md‎

Lines changed: 39 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,30 @@
11
# CHANGELOG
22

3+
## v1.0.0 (2025-03-27)
4+
5+
**Enhancements:**
6+
7+
- Full support for ISOBMFF image formats (box-type): HEIF, HEIC and AVIF.
8+
- Reordering types being checked in guessing functions (`{seems?,type,info}/1`), focusing on recent trends.
9+
- Docs and testing improvements.
10+
11+
**News:**
12+
13+
- First major release of ExImageInfo, after years working without issues and really stable.
14+
15+
**Statistics:**
16+
17+
- 79 TDD Tests:
18+
- including 32 images being tested, also fetching external images on-the-fly.
19+
- supporting partial streams and including many binary mocks/fixtures (up to 50 tests to verify edge cases).
20+
- Code coverage of 98.3%.
21+
- Supports 13 image formats and 23 variants.
22+
- No dependencies.
23+
24+
**Acknowledgments:**
25+
26+
- @bu6n for the first attempts about heic/heif/avif support and starting as a reviewer.
27+
328
## v0.2.7 (2025-03-05)
429

530
**Enhancements:**
@@ -47,9 +72,9 @@
4772

4873
**Enhancements:**
4974

50-
- By request of a GitHub user: support for another variant of webp
51-
- Studied and integrated the webpVP8X format (bitstream animated)
52-
- Added 2 new tests for animated photos: gif and webp vp8x
75+
- By request of a GitHub user: support for another variant of webp.
76+
- Studied and integrated the webpVP8X format (bitstream animated).
77+
- Added 2 new tests for animated photos: gif and webp vp8x.
5378

5479
## v0.2.3 (2018-05-21)
5580

@@ -94,14 +119,14 @@
94119
**Enhancements:**
95120

96121
- The guessing function is ordered by global usage [usage of image file formats](https://w3techs.com/technologies/overview/image_format/all), but still keeping *png* as the first one.
97-
- Added support for *ico*, *jp2* (*jpeg 2000*) and the collection of *pnm* (*pbm*, *pgm* and *ppm*)
98-
- *ico* gets the dimensions of the largest image contained (not the first found)
122+
- Added support for *ico*, *jp2* (*jpeg 2000*) and the collection of *pnm* (*pbm*, *pgm* and *ppm*).
123+
- *ico* gets the dimensions of the largest image contained (not the first found).
99124

100125
**Statistics:**
101126

102-
- 54 TDD Tests
103-
- Code coverage of 98.3%
104-
- 10 image formats supported
127+
- 54 TDD Tests.
128+
- Code coverage of 98.3%.
129+
- 10 image formats supported.
105130

106131
**News:**
107132

@@ -111,20 +136,20 @@
111136

112137
**Enhancements:**
113138

114-
- Warnings corrected (compiling)
139+
- Warnings corrected (compiling).
115140

116141
**Statistics:**
117142

118-
- 34 TDD Tests
119-
- Code coverage of 97.6%
120-
- 7 image formats supported
143+
- 34 TDD Tests.
144+
- Code coverage of 97.6%.
145+
- 7 image formats supported.
121146

122147
**News:**
123148

124-
- Initial release (published) + Docs (gh-pages)
149+
- Initial release (published) + Docs (gh-pages).
125150

126151
## v0.1.0 (2016-08-11)
127152

128153
**News:**
129154

130-
- Initial release (pre-publish)
155+
- Initial release (pre-publish).

‎README.md‎

Lines changed: 53 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
# ExImageInfo
44

5-
[![Elixir](https://img.shields.io/badge/made_in-elixir-9900cc.svg?style=flat-square)](http://elixir-lang.org) [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/Group4Layers/ex_image_info/master/LICENSE.md) [![Coverage](https://img.shields.io/badge/coverage-98.4%25-green.svg)](https://github.com/Group4Layers/ex_image_info) [![Tests](https://img.shields.io/badge/tests-79%2F79-green.svg)](https://github.com/Group4Layers/ex_image_info)
5+
[![v1.0.0](https://img.shields.io/badge/version-1.0.0-a1c43c.svg)](https://hex.pm/packages/ex_image_info) [![Elixir](https://img.shields.io/badge/made_in-elixir-9900cc.svg)](http://elixir-lang.org) [![Elixir ≥1.13](https://img.shields.io/badge/-≥1.13-9900cc.svg?logo=Elixir)](http://elixir-lang.org) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/Group4Layers/ex_image_info/master/LICENSE.md) [![Coverage](https://img.shields.io/badge/coverage-98.4%25-green.svg)](https://github.com/Group4Layers/ex_image_info) [![Tests](https://img.shields.io/badge/tests-79%2F79-green.svg)](https://github.com/Group4Layers/ex_image_info)
66

77
ExImageInfo is an Elixir library to parse images (binaries) and get the dimensions (size), detected mime-type and overall validity for a set of image formats. It is the fastest and supports multiple formats.
88

@@ -48,18 +48,17 @@ supported by the library.
4848
Supported formats (image type to be parsed as):
4949
- `:bmp`
5050
- `:gif`
51-
- `:ico` (since `v0.2.0`)
52-
- `:jpeg`
53-
- `:jpg` (alias of `jpeg` since `v0.2.3`)
54-
- `:jp2` (since `v0.2.0`)
51+
- `:ico`
52+
- `:jpeg` (`:jpg` alias since `v0.2.3`)
53+
- `:jp2`
5554
- `:png`
56-
- `:pnm` (since `v0.2.0`)
55+
- `:pnm`
5756
- `:psd`
5857
- `:tiff`
59-
- `:webp` (VP8X animated since `v0.2.4`)
60-
- `:avif` (since `v1.0.0`)
61-
- `:heic` (since `v1.0.0`)
62-
- `:heif` (since `v1.0.0`)
58+
- `:webp`
59+
- `:avif`
60+
- `:heic`
61+
- `:heif`
6362

6463
## Mime-types and Variants
6564

@@ -69,43 +68,54 @@ mime-type).
6968

7069
Each mime-type can be linked to at least one variant type:
7170

72-
| mime-type | variant type | description |
73-
|---------------------------|-------------| ------------------ |
74-
| `image/avif` | `AVIF` | |
75-
| `image/avif-sequence` | `AVIFS` | |
76-
| `image/bmp` | `BMP` | |
77-
| `image/gif` | `GIF87a` | 87a gif spec |
78-
| `image/gif` | `GIF89a` | 89a gif spec |
79-
| `image/heic` | `HEIC` | |
80-
| `image/heic-sequence` | `HEICS` | |
81-
| `image/heif` | `HEIF` | |
82-
| `image/heif-sequence` | `HEIFS` | |
83-
| `image/x-icon` | `ICO` | |
84-
| `image/jp2` | `JP2` | JPEG2000 |
85-
| `image/jpeg` | `baseJPEG` | baseline JPEG |
86-
| `image/jpeg` | `progJPEG` | progressive JPEG |
87-
| `image/png` | `PNG` | |
88-
| `image/x-portable-anymap` | `PNMpbm` | Portable BitMap |
89-
| `image/x-portable-anymap` | `PNMpgm` | Portable GrayMap |
90-
| `image/x-portable-anymap` | `PNMppm` | Portable PixMap |
91-
| `image/psd` | `PSD` | |
92-
| `image/tiff` | `TIFFII` | II variant |
93-
| `image/tiff` | `TIFFMM` | MM variant |
94-
| `image/webp` | `webpVP8` | lossy |
95-
| `image/webp` | `webpVP8L` | lossless |
96-
| `image/webp` | `webpVP8X` | animated |
97-
98-
The variant type is created just to provide a bit more of information
99-
for every image format (if applicable).
100-
101-
*Note*: `:avif`, `:heic`, `:heif` and `:ico` return the dimensions of the primary (if available in that format) or the largest image contained (not the first found).
102-
103-
The guessing functions try to detect the format of the binary by testing every available type based on its global usage and current trends (popularity, [usage of image file formats](https://w3techs.com/technologies/overview/image_format/all)):
71+
| mime-type | variant type | description | since version |
72+
|---------------------------|--------------|--------------------|---------------|
73+
| `image/avif` | `AVIF` | | v1.0.0 |
74+
| `image/avif-sequence` | `AVIFS` | | v1.0.0 |
75+
| `image/bmp` | `BMP` | | |
76+
| `image/gif` | `GIF87a` | 87a gif spec | |
77+
| `image/gif` | `GIF89a` | 89a gif spec | |
78+
| `image/heic` | `HEIC` | | v1.0.0 |
79+
| `image/heic-sequence` | `HEICS` | | v1.0.0 |
80+
| `image/heif` | `HEIF` | | v1.0.0 |
81+
| `image/heif-sequence` | `HEIFS` | | v1.0.0 |
82+
| `image/x-icon` | `ICO` | | v0.2.0 |
83+
| `image/jp2` | `JP2` | JPEG2000 | v0.2.0 |
84+
| `image/jpeg` | `baseJPEG` | baseline JPEG | |
85+
| `image/jpeg` | `progJPEG` | progressive JPEG | |
86+
| `image/png` | `PNG` | | |
87+
| `image/x-portable-anymap` | `PNMpbm` | Portable BitMap | v0.2.0 |
88+
| `image/x-portable-anymap` | `PNMpgm` | Portable GrayMap | v0.2.0 |
89+
| `image/x-portable-anymap` | `PNMppm` | Portable PixMap | v0.2.0 |
90+
| `image/psd` | `PSD` | | |
91+
| `image/tiff` | `TIFFII` | II variant | |
92+
| `image/tiff` | `TIFFMM` | MM variant | |
93+
| `image/webp` | `webpVP8` | lossy | |
94+
| `image/webp` | `webpVP8L` | lossless | |
95+
| `image/webp` | `webpVP8X` | animated | v0.2.4 |
96+
97+
The variant type is created just to provide a bit more of information for every image format (if applicable).
98+
If version is empty, it means that it was supported since the initial release.
99+
100+
Formats (maybe) containing multiple images:
101+
- `:ico` returns the dimensions of the largest image found.
102+
- `:heif`, `:heic` and `:avif` return the dimensions of the main image being selected (`primary_box`).
103+
104+
The guessing functions try to detect the format of the binary by testing every available type based on its
105+
global usage and current trends (popularity, [usage of image file formats](https://w3techs.com/technologies/overview/image_format/all)):
104106
- `jpeg`, `png`, `webp`, `avif`, `gif`, `heic`, `heif`, `bmp`, `ico`, `tiff`, `psd`, `jp2`, `pnm`
105107

106108
**Warnings:**
107109

108-
- Use with caution the formats *ico*, *jp2* and the family *pnm*. They are implemented without following other libraries (just reading the specs - sometimes working with old drafts like *jp2*). You can support this library by providing more tests and image *fixtures* or requesting other variants to be tested.
110+
- Use with caution the formats *ico*, *jp2* and the family *pnm*. They are implemented without following
111+
other libraries (just reading the specs - sometimes working with old drafts like *jp2*).
112+
- ISOBMFF format (*heif*, *heic* and *avif*) is the most complex format being supported, with most parts
113+
being implemented following the specs and testing against binary streams manually produced.
114+
Please, use with caution and report any issue found.
115+
116+
**Contributions:** you can support this library by providing more tests, image *fixtures* (like `image/heic-sequence`),
117+
increasing code coverage or extending support for other variants.
118+
109119

110120
## Installation
111121

‎lib/ex_image_info.ex‎

Lines changed: 67 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
defmodule ExImageInfo do
22
@moduledoc """
3-
ExImageInfo is an Elixir library to parse images (binaries) and get the dimensions (size), detected mime-type and overall validity for a set of image formats. Main module to parse a binary and get if it seems to be an image (validity), the mime-type (and variant detected) and the dimensions of the image, based on a specific image format.
3+
ExImageInfo is an Elixir library to parse images (binaries) and get the dimensions (size),
4+
detected mime-type and overall validity for a set of image formats. Main module to parse a
5+
binary and get if it seems to be an image (validity), the mime-type (and variant detected)
6+
and the dimensions of the image, based on a specific image format.
47
58
It has convention functions to guess the type of an image
69
by trying the formats supported by the library.
@@ -21,15 +24,17 @@ defmodule ExImageInfo do
2124
Supported formats (image type to be parsed as):
2225
- `:bmp`
2326
- `:gif`
24-
- `:ico` (new in `v0.2.0`)
25-
- `:jpeg`
26-
- `:jpg` (alias of `jpeg` in `v0.2.3`)
27-
- `:jp2` (new in `v0.2.0`)
27+
- `:ico`
28+
- `:jpeg` (`:jpg` alias since `v0.2.3`)
29+
- `:jp2`
2830
- `:png`
29-
- `:pnm` (new in `v0.2.0`)
31+
- `:pnm`
3032
- `:psd`
3133
- `:tiff`
32-
- `:webp` (VP8X animated in `v0.2.4`)
34+
- `:webp`
35+
- `:avif`
36+
- `:heic`
37+
- `:heif`
3338
3439
## Mime-types and Variants
3540
@@ -39,39 +44,53 @@ defmodule ExImageInfo do
3944
4045
Each mime-type can be linked to at least one variant type:
4146
42-
| mime-type | variant type | description |
43-
| ------------------------- | ------------ | ------------------ |
44-
| `image/avif` | `AVIF` | |
45-
| `image/avif-sequence | `AVIFS` | |
46-
| `image/bmp` | `BMP` | |
47-
| `image/gif` | `GIF87a` | 87a gif spec |
48-
| `image/gif` | `GIF89a` | 89a gif spec |
49-
| `image/heic` | `HEIC` | |
50-
| `image/heic-sequence` | `HEICS` | |
51-
| `image/heif` | `HEIF` | |
52-
| `image/heif-sequence` | `HEIFS` | |
53-
| `image/x-icon` | `ICO` | |
54-
| `image/jpeg` | `baseJPEG` | baseline JPEG |
55-
| `image/jpeg` | `progJPEG` | progressive JPEG |
56-
| `image/jp2` | `JP2` | JPEG2000 |
57-
| `image/png` | `PNG` | |
58-
| `image/x-portable-anymap` | `PNMpbm` | Portable BitMap |
59-
| `image/x-portable-anymap` | `PNMpgm` | Portable GrayMap |
60-
| `image/x-portable-anymap` | `PNMppm` | Portable PixMap |
61-
| `image/psd` | `PSD` | |
62-
| `image/tiff` | `TIFFII` | II variant |
63-
| `image/tiff` | `TIFFMM` | MM variant |
64-
| `image/webp` | `webpVP8` | lossy |
65-
| `image/webp` | `webpVP8L` | lossless |
66-
| `image/webp` | `webpVP8X` | animated |
67-
68-
The variant type is created just to provide a bit more of information
69-
for every image format (if applicable).
70-
71-
*Note*: `:ico` returns the dimensions of the largest image contained (not the first found).
72-
73-
The guessing functions try to detect the format of the binary by testing every available type based on its global usage (popularity, [usage of image file formats](https://w3techs.com/technologies/overview/image_format/all), but still keeping the `:png` as the first one):
74-
- `:png`, `:jpeg`, `:gif`, `:bmp`, `:ico`, `:tiff`, `:webp`, `:psd`, `:jp2`, `:pnm`, `:avif`, `:heic`, `:heif`
47+
| mime-type | variant type | description | since version |
48+
|---------------------------|--------------|--------------------|---------------|
49+
| `image/avif` | `AVIF` | | v1.0.0 |
50+
| `image/avif-sequence` | `AVIFS` | | v1.0.0 |
51+
| `image/bmp` | `BMP` | | |
52+
| `image/gif` | `GIF87a` | 87a gif spec | |
53+
| `image/gif` | `GIF89a` | 89a gif spec | |
54+
| `image/heic` | `HEIC` | | v1.0.0 |
55+
| `image/heic-sequence` | `HEICS` | | v1.0.0 |
56+
| `image/heif` | `HEIF` | | v1.0.0 |
57+
| `image/heif-sequence` | `HEIFS` | | v1.0.0 |
58+
| `image/x-icon` | `ICO` | | v0.2.0 |
59+
| `image/jp2` | `JP2` | JPEG2000 | v0.2.0 |
60+
| `image/jpeg` | `baseJPEG` | baseline JPEG | |
61+
| `image/jpeg` | `progJPEG` | progressive JPEG | |
62+
| `image/png` | `PNG` | | |
63+
| `image/x-portable-anymap` | `PNMpbm` | Portable BitMap | v0.2.0 |
64+
| `image/x-portable-anymap` | `PNMpgm` | Portable GrayMap | v0.2.0 |
65+
| `image/x-portable-anymap` | `PNMppm` | Portable PixMap | v0.2.0 |
66+
| `image/psd` | `PSD` | | |
67+
| `image/tiff` | `TIFFII` | II variant | |
68+
| `image/tiff` | `TIFFMM` | MM variant | |
69+
| `image/webp` | `webpVP8` | lossy | |
70+
| `image/webp` | `webpVP8L` | lossless | |
71+
| `image/webp` | `webpVP8X` | animated | v0.2.4 |
72+
73+
The variant type is created just to provide a bit more of information for every image format (if applicable).
74+
If version is empty, it means that it was supported since the initial release.
75+
76+
Formats (maybe) containing multiple images:
77+
- `:ico` returns the dimensions of the largest image found.
78+
- `:heif`, `:heic` and `:avif` return the dimensions of the main image being selected (`primary_box`).
79+
80+
The guessing functions try to detect the format of the binary by testing every available type based on its
81+
global usage and current trends (popularity, [usage of image file formats](https://w3techs.com/technologies/overview/image_format/all)):
82+
- `jpeg`, `png`, `webp`, `avif`, `gif`, `heic`, `heif`, `bmp`, `ico`, `tiff`, `psd`, `jp2`, `pnm`
83+
84+
**Warnings:**
85+
86+
- Use with caution the formats *ico*, *jp2* and the family *pnm*. They are implemented without following
87+
other libraries (just reading the specs - sometimes working with old drafts like *jp2*).
88+
- ISOBMFF format (*heif*, *heic* and *avif*) is the most complex format being supported, with most parts
89+
being implemented following the specs and testing against binary streams manually produced.
90+
Please, use with caution and report any issue found.
91+
92+
**Contributions:** you can support this library by providing more tests, image *fixtures* (like `image/heic-sequence`),
93+
increasing code coverage or extending support for other variants.
7594
"""
7695
alias ExImageInfo.Types.AVIF
7796
alias ExImageInfo.Types.BMP
@@ -106,7 +125,7 @@ defmodule ExImageInfo do
106125
:pnm
107126
]
108127

109-
@typedoc "The supported image formats"
128+
@typedoc "The supported image formats."
110129
@type image_format ::
111130
:jpeg
112131
| :png
@@ -141,7 +160,8 @@ defmodule ExImageInfo do
141160
iex> ExImageInfo.seems? <<0x89504E470D0A1A0A::size(64)>>, :webp
142161
false
143162
144-
`ExImageInfo.seems?/2` and `ExImageInfo.seems?/1` does not necessarily needs a real image (as it is shown in the previous example) because it just checks the signature of every file format.
163+
`ExImageInfo.seems?/2` and `ExImageInfo.seems?/1` does not necessarily needs a real image
164+
(as it is shown in the previous example) because it just checks the signature of every file format.
145165
146166
Usually it is used as:
147167
@@ -183,7 +203,8 @@ defmodule ExImageInfo do
183203
iex> ExImageInfo.seems? <<0x384250::size(24)>>
184204
nil
185205
186-
`ExImageInfo.seems?/2` and `ExImageInfo.seems?/1` does not necessarily needs a real image (as it is shown in the previous example) because it just checks the signature of every file format.
206+
`ExImageInfo.seems?/2` and `ExImageInfo.seems?/1` does not necessarily needs a real image
207+
(as it is shown in the previous example) because it just checks the signature of every file format.
187208
188209
Usually it is used as:
189210
@@ -298,7 +319,7 @@ defmodule ExImageInfo do
298319
299320
If a binary is malformed, it returns `nil`, even if other calls like `type` or `seems?` return valid types.
300321
301-
{ExImageInfo.type(malformed_heif_binary), ExImageInfo.info(malformed_heif_binary)}
322+
{ExImageInfo.type(malformed_heif_binary, :heif), ExImageInfo.info(malformed_heif_binary, :heif)}
302323
# {{"image/heif", "HEIF"}, nil}
303324
"""
304325
@spec info(binary, format :: atom) ::
@@ -323,7 +344,8 @@ defmodule ExImageInfo do
323344
def info(_, _), do: nil
324345

325346
@doc """
326-
Gets the mime-type, variant-type and dimensions (width, height) for the given image binary (*guessed* version of `ExImageInfo.info/2`).
347+
Gets the mime-type, variant-type and dimensions (width, height) for the given image binary
348+
(*guessed* version of `ExImageInfo.info/2`).
327349
328350
Possible [Mime-types and Variants](#module-mime-types-and-variants) to be returned.
329351

0 commit comments

Comments
 (0)