Skip to content

Commit 42b277f

Browse files
K0lb3K0lb3
committed
add docs page
1 parent b2a04c9 commit 42b277f

File tree

9 files changed

+250
-81
lines changed

9 files changed

+250
-81
lines changed

‎.github/workflows/doc.yml

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# clone of: https://github.com/mitmproxy/pdoc/blob/main/.github/workflows/docs.yml
2+
name: astc-encoder-py docs
3+
4+
# build the documentation whenever there are new commits on main
5+
on:
6+
push:
7+
branches:
8+
- main
9+
# Alternative: only build for tags.
10+
# tags:
11+
# - '*'
12+
13+
# security: restrict permissions for CI jobs.
14+
permissions:
15+
contents: read
16+
17+
jobs:
18+
# Build the documentation and upload the static HTML files as an artifact.
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
with:
24+
submodules: recursive
25+
26+
- uses: actions/setup-python@v5
27+
with:
28+
python-version: '3.12'
29+
30+
- name: Install local package
31+
run: pip install -e .
32+
33+
- name: Install pdoc
34+
run: pip install pdoc pillow
35+
36+
# ADJUST THIS: build your documentation into docs/.
37+
# We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
38+
- run: pdoc --docformat numpy -o docs/ ./astc_encoder
39+
40+
- uses: actions/upload-pages-artifact@v3
41+
with:
42+
path: docs/
43+
44+
# Deploy the artifact to GitHub pages.
45+
# This is a separate job so that only actions/deploy-pages has the necessary permissions.
46+
deploy:
47+
needs: build
48+
runs-on: ubuntu-latest
49+
permissions:
50+
pages: write
51+
id-token: write
52+
environment:
53+
name: github-pages
54+
url: ${{ steps.deployment.outputs.page_url }}
55+
steps:
56+
- id: deployment
57+
uses: actions/deploy-pages@v4

‎.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
11
test.py
2+
/docs
3+
/wip
4+
*.exe
5+
6+
# Ruff
7+
.ruff_cache/
28

39
# Editors
410
.vscode/

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,4 +80,4 @@ img = Image.frombytes("RGBA", img.size, image_dec.data)
8080
- [x] ~~export ASTCImage directly to PIL.Image~~ via PIL.ImageDecoder
8181
- [ ] SVE support for arm
8282
- [x] tests
83-
- [ ] docs page
83+
- [x] docs page

‎astc_encoder/__init__.py

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,25 @@
1+
"""astc-encoder-py is a Python binding of [astc-encoder](https://github.com/ARM-software/astc-encoder).
2+
3+
It can compress images into astc textures and decompress astc textures into images.
4+
To yield the best performance, it checks the host CPU and imports the appropriate encoder implementation.
5+
Currently this is only supported on x86_64, all others use an encoder with no SIMD optimizations.
6+
The exception is aarch64, which uses the neon encoder by default.
7+
"""
8+
19
__version__ = "0.1.6"
210

311
from .enum import (
4-
ASTCConfigFlags,
5-
ASTCProfile,
6-
ASTCQualityPreset,
7-
ASTCSwizzleComponentSelector,
8-
ASTCType,
12+
ASTCConfigFlags as ASTCConfigFlags,
13+
ASTCProfile as ASTCProfile,
14+
ASTCQualityPreset as ASTCQualityPreset,
15+
ASTCSwizzleComponentSelector as ASTCSwizzleComponentSelector,
16+
ASTCType as ASTCType,
917
)
1018

1119
from .encoder import (
12-
ASTCConfig,
13-
ASTCContext,
14-
ASTCImage,
15-
ASTCSwizzle,
16-
ASTCError,
20+
ASTCConfig as ASTCConfig,
21+
ASTCContext as ASTCContext,
22+
ASTCImage as ASTCImage,
23+
ASTCSwizzle as ASTCSwizzle,
24+
ASTCError as ASTCError,
1725
)

‎astc_encoder/encoder.py

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
"""A module provides the ASTC encoder.
2+
3+
It checks the host CPU and imports the appropriate encoder implementation.
4+
"""
5+
16
from archspec.cpu import host
27

38
local_host = host()
@@ -8,14 +13,14 @@
813
# archspec doesn't detect the relevant features for arm
914
# so we assume neon is available,
1015
# as it's unlikely for a device using the lib to not have it
11-
from ._encoder_neon import *
16+
from ._encoder_neon import * # type: ignore
1217
elif local_host.family.name == "x86_64":
1318
if "avx2" in local_host.features:
14-
from ._encoder_avx2 import *
19+
from ._encoder_avx2 import * # type: ignore
1520
elif "sse4_1" in local_host.features:
16-
from ._encoder_sse41 import *
21+
from ._encoder_sse41 import * # type: ignore
1722
elif "sse2" in local_host.features:
18-
from ._encoder_sse2 import *
23+
from ._encoder_sse2 import * # type: ignore
1924
except ImportError:
2025
pass
2126

‎astc_encoder/encoder.pyi

Lines changed: 40 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ class ASTCImage:
1616
3D image are passed in as an array of 2D slices.
1717
Each slice has identical size and color format.
1818
19-
Members
20-
-------
19+
Attributes
20+
----------
2121
dim_x : int
2222
The X dimension of the image, in texels.
2323
dim_y : int
@@ -54,35 +54,35 @@ class ASTCConfig:
5454
config applies to the component that exists after any compression data swizzle is applied.
5555
5656
Legal block sizes are:
57-
2d:
58-
4x4
59-
5x4
60-
5x5
61-
6x5
62-
6x6
63-
8x5
64-
8x6
65-
8x8
66-
10x5
67-
10x6
68-
10x8
69-
10x10
70-
12x10
71-
12x12
72-
3d:
73-
3x3x3
74-
4x3x3
75-
4x4x3
76-
4x4x4
77-
5x4x4
78-
5x5x4
79-
5x5x5
80-
6x5x5
81-
6x6x5
82-
6x6x6
57+
- 2d
58+
- 4x4
59+
- 5x4
60+
- 5x5
61+
- 6x5
62+
- 6x6
63+
- 8x5
64+
- 8x6
65+
- 8x8
66+
- 10x5
67+
- 10x6
68+
- 10x8
69+
- 10x10
70+
- 12x10
71+
- 12x12
72+
- 3d
73+
- 3x3x3
74+
- 4x3x3
75+
- 4x4x3
76+
- 4x4x4
77+
- 5x4x4
78+
- 5x5x4
79+
- 5x5x5
80+
- 6x5x5
81+
- 6x6x5
82+
- 6x6x6
8383
84-
Members
85-
-------
84+
Attributes
85+
----------
8686
profile : ASTCProfile
8787
The color profile.
8888
flags : int
@@ -204,7 +204,7 @@ class ASTCConfig:
204204
class ASTCSwizzle:
205205
"""A texel component swizzle.
206206
207-
Members
207+
Attributes
208208
----------
209209
r : ASTCSwizzleComponentSelector
210210
The red component selector.
@@ -234,13 +234,13 @@ class ASTCSwizzle:
234234
Create a swizzle from a string.
235235
236236
The string must be 4 characters long, with each character being one of:
237-
r/R: Red component.
238-
g/G: Green component.
239-
b/B: Blue component.
240-
a/A: Alpha component.
241-
0: always 0
242-
1: always 1
243-
z/Z: Reconstructed normal vector Z component.
237+
- r/R: Red component.
238+
- g/G: Green component.
239+
- b/B: Blue component.
240+
- a/A: Alpha component.
241+
- 0: always 0
242+
- 1: always 1
243+
- z/Z: Reconstructed normal vector Z component.
244244
"""
245245
...
246246

@@ -249,8 +249,8 @@ class ASTCContext:
249249
threads: int
250250

251251
def __init__(self, config: ASTCConfig, threads: int = 1) -> None: ...
252-
def compress(self, image: ASTCImage, swizzle: str) -> bytes: ...
253-
def decompress(self, data: bytes, image: ASTCImage, swizzle: str) -> ASTCImage: ...
252+
def compress(self, image: ASTCImage, swizzle: ASTCSwizzle) -> bytes: ...
253+
def decompress(self, data: bytes, image: ASTCImage, swizzle: ASTCSwizzle) -> ASTCImage: ...
254254

255255
class ASTCError(Exception):
256256
pass

‎astc_encoder/enum.py

Lines changed: 76 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1+
"""The enumeration classes for the ASTC encoder."""
2+
13
from enum import IntEnum, IntFlag
24

35

46
class ASTCProfile(IntEnum):
5-
"""The ASTC profile.
7+
"""A codec color profile.
68
7-
Parameters
9+
Attributes
810
----------
911
LDR_SRGB : int = 0
1012
The LDR sRGB color profile.
@@ -23,9 +25,11 @@ class ASTCProfile(IntEnum):
2325

2426

2527
class ASTCQualityPreset(IntEnum):
26-
"""The ASTC quality preset.
28+
"""The quality presets.
29+
30+
These values are just presets, the user can set the quality to any value between 0 and 100.
2731
28-
Parameters
32+
Attributes
2933
----------
3034
FASTEST : int = 0
3135
The fastest, lowest quality, search preset.
@@ -50,6 +54,72 @@ class ASTCQualityPreset(IntEnum):
5054

5155

5256
class ASTCConfigFlags(IntFlag):
57+
"""The configuration flags.
58+
59+
Attributes
60+
----------
61+
MAP_NORMAL : int = 1 << 0
62+
Enable normal map compression.
63+
64+
Input data will be treated a two component normal map,
65+
storing X and Y, and the codec will optimize for angular error rather than simple linear PSNR.
66+
In this mode the input swizzle should be e.g.
67+
- rrrg (the default ordering for ASTC normals on the command line)
68+
- gggr (the ordering used by BC5n)
69+
70+
USE_DECODE_UNORM8 : int = 1 << 1
71+
Enable compression heuristics that assume use of decode_unorm8 decode mode.
72+
73+
The decode_unorm8 decode mode rounds differently to the decode_fp16 decode mode,
74+
so enabling this flag during compression will allow the compressor to use
75+
the correct rounding when selecting encodings.
76+
This will improve the compressed image quality if your application is using the decode_unorm8 decode mode,
77+
but will reduce image quality if using decode_fp16.
78+
Note that LDR_SRGB images will always use decode_unorm8 for the RGB channels,
79+
irrespective of this setting.
80+
81+
USE_APLHA_WEIGHT : int = 1 << 2
82+
Enable alpha weighting.
83+
84+
The input alpha value is used for transparency, so errors in the RGB components are weighted by
85+
the transparency level. This allows the codec to more accurately encode the alpha value in areas
86+
where the color value is less significant.
87+
USE_PERCEPTUAL : int = 1 << 3
88+
Enable perceptual error metrics.
89+
90+
This mode enables perceptual compression mode, which will optimize for perceptual error rather
91+
than best PSNR. Only some input modes support perceptual error metrics.
92+
93+
SELF_DECOMPRESS_ONLY : int = 1 << 4
94+
Create a self-decompression context.
95+
96+
This mode configures the compressor so that it is only guaranteed to be able to decompress images
97+
that were actually created using the current context.
98+
This is the common case for compression use cases, and setting this flag enables additional optimizations,
99+
but does mean that the context cannot reliably decompress arbitrary ASTC images.
100+
101+
MAP_RGBM : int = 1 << 6
102+
Enable RGBM map compression.
103+
104+
Input data will be treated as HDR data that has been stored in an LDR RGBM-encoded wrapper format.
105+
Data must be preprocessed by the user to be in LDR RGBM format before calling the compression function,
106+
this flag is only used to control the use of RGBM-specific heuristics and error metrics.
107+
108+
**IMPORTANT**:
109+
110+
The ASTC format is prone to bad failure modes with unconstrained RGBM data;
111+
very small M values can round to zero due to quantization and result in black or white pixels.
112+
It is highly recommended that the minimum value of M used in the encoding is kept above a lower threshold (try 16 or 32).
113+
Applying this threshold reduces the number of very dark colors that can be represented,
114+
but is still higher precision than 8-bit LDR.
115+
116+
When this flag is set the value of ``c rgbm_m_scale`` in the context must be set to the RGBM scale factor used during reconstruction.
117+
This defaults to 5 when in RGBM mode.
118+
It is recommended that the value of ``c cw_a_weight`` is set to twice the value of the multiplier scale,
119+
ensuring that the M value is accurately encoded.
120+
This defaults to 10 when in RGBM mode, matching the default scale factor.
121+
"""
122+
53123
MAP_NORMAL = 1 << 0
54124
USE_DECODE_UNORM8 = 1 << 1
55125
USE_APLHA_WEIGHT = 1 << 2
@@ -62,7 +132,7 @@ class ASTCConfigFlags(IntFlag):
62132
class ASTCType(IntEnum):
63133
"""A texel component data format.
64134
65-
Parameters
135+
Attributes
66136
----------
67137
U8 : int = 0
68138
Unorm 8-bit data per component.
@@ -80,7 +150,7 @@ class ASTCType(IntEnum):
80150
class ASTCSwizzleComponentSelector(IntEnum):
81151
"""A codec component swizzle selector.
82152
83-
Parameters
153+
Attributes
84154
----------
85155
R : int = 0
86156
Select the red component.

0 commit comments

Comments
 (0)