brulegfx 0.0.6__tar.gz

brulegfx-0.0.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 cubicibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brulegfx-0.0.6/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: brulegfx
+Version: 0.0.6
+Summary: Bitmap utilities (RLE, RGBA quantization, Segmentation)
+Author-email: cubicibo <cubicibo@outlook.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0.1
+Requires-Dist: numba
+Requires-Dist: opencv-python
+Dynamic: license-file
+
+# Brule
+Collection of C extension modules for SUPer with pure-python fallbacks
+- Brule: Bitmap RUn LEngth coder and decoder.
+- LayoutEngine: An optimal two-rects layout finder for a sequence of images.
+- HexTree: RGBA image quantizer (turbo, good quality)
+- QtzrUTC: RGBA image quantizer (fast, excellent quality)
+
+## Brule brief
+Brule implements 2 or 3 times the same function, and select the fastest implementation available at runtime.
+- C (fastest)
+- numba (only for the RLE codec)
+- pure Python (slow)
+
+For the encoder, the C implementation is up to 20 times faster than numba. The pure Python implementation does not compete and is only there for convenience.
+
+## Install
+Given `./brule` the (cloned) repository:
+```bash
+$ python -m pip install ./brule
+```
+
+## Example (RLE Codec)
+
+The run-length codec is operated like this:
+```python
+>>> from brule import Brule
+>>> import numpy as np
+>>> bitmap_orig = np.ones((1080, 1920), np.uint8)
+>>> rle_data = Brule.encode(bitmap_orig)
+>>> bitmap = Brule.decode(rle_data)
+>>> assert np.all(bitmap == bitmap_orig)
+True
+```
+
+## Example (HexTree, QtzrUTC)
+The image quantizer is used like this:
+```python
+>>> from brule import HexTree, QtzrUTC
+>>> import numpy as np
+>>> from PIL import Image
+>>> rgba = np.asarray(Image.open(...).convert('RGBA'))
+>>> #quantize with 255 colours 
+>>> bitmap1, palette1 = HexTree.quantize(rgba, 255)
+>>> bitmap2, palette2 = QtzrUTC.quantize(rgba, 255)
+```
+
+## Credits
+- https://github.com/pallets/markupsafe markupsafe for the pip install fallback mechanism with compiled extensions.
+- https://github.com/DarthSim/quantizr for Qtzr

brulegfx-0.0.6/README.md

@@ -0,0 +1,49 @@
+# Brule
+Collection of C extension modules for SUPer with pure-python fallbacks
+- Brule: Bitmap RUn LEngth coder and decoder.
+- LayoutEngine: An optimal two-rects layout finder for a sequence of images.
+- HexTree: RGBA image quantizer (turbo, good quality)
+- QtzrUTC: RGBA image quantizer (fast, excellent quality)
+
+## Brule brief
+Brule implements 2 or 3 times the same function, and select the fastest implementation available at runtime.
+- C (fastest)
+- numba (only for the RLE codec)
+- pure Python (slow)
+
+For the encoder, the C implementation is up to 20 times faster than numba. The pure Python implementation does not compete and is only there for convenience.
+
+## Install
+Given `./brule` the (cloned) repository:
+```bash
+$ python -m pip install ./brule
+```
+
+## Example (RLE Codec)
+
+The run-length codec is operated like this:
+```python
+>>> from brule import Brule
+>>> import numpy as np
+>>> bitmap_orig = np.ones((1080, 1920), np.uint8)
+>>> rle_data = Brule.encode(bitmap_orig)
+>>> bitmap = Brule.decode(rle_data)
+>>> assert np.all(bitmap == bitmap_orig)
+True
+```
+
+## Example (HexTree, QtzrUTC)
+The image quantizer is used like this:
+```python
+>>> from brule import HexTree, QtzrUTC
+>>> import numpy as np
+>>> from PIL import Image
+>>> rgba = np.asarray(Image.open(...).convert('RGBA'))
+>>> #quantize with 255 colours 
+>>> bitmap1, palette1 = HexTree.quantize(rgba, 255)
+>>> bitmap2, palette2 = QtzrUTC.quantize(rgba, 255)
+```
+
+## Credits
+- https://github.com/pallets/markupsafe markupsafe for the pip install fallback mechanism with compiled extensions.
+- https://github.com/DarthSim/quantizr for Qtzr

brulegfx-0.0.6/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=64", "numpy>=2.0.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brulegfx"
+version = "0.0.6"
+authors = [{ name = "cubicibo", email = "cubicibo@outlook.com" }]
+description = "Bitmap utilities (RLE, RGBA quantization, Segmentation)"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [ "numpy>=2.0.1", "numba", "opencv-python", ]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+zip-safe = false
+
+[tool.setuptools.packages.find]
+where = ["src"]

brulegfx-0.0.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brulegfx-0.0.6/setup.py

@@ -0,0 +1,123 @@
+"""
+MIT License
+
+Copyright (c) 2024-26 cubicibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+import os
+import setuptools
+import sysconfig
+import numpy as np
+from setuptools.command.build_ext import build_ext
+from setuptools.errors import CCompilerError
+from setuptools.errors import ExecError
+from setuptools.errors import PlatformError
+
+NAME = 'brule'
+
+# This fallback build system is taken from  https://github.com/pallets/markupsafe (BSD-3 license)
+class BuildFailed(Exception):
+    pass
+
+class ve_build_ext(build_ext):
+    """This class allows C extension building to fail."""
+    def run(self):
+        try:
+            super().run()
+        except PlatformError as e:
+            raise BuildFailed() from e
+
+    def build_extension(self, ext):
+        try:
+            super().build_extension(ext)
+        except (CCompilerError, ExecError, PlatformError) as e:
+            raise BuildFailed() from e
+        except ValueError as e:
+            import sys
+            # this can happen on Windows 64 bit, see Python issue 7511
+            if "'path'" in str(sys.exc_info()[1]):
+                raise BuildFailed() from e
+            raise
+
+def show_message(*lines):
+    print("=" * 74)
+    for line in lines:
+        print(line)
+    print("=" * 74)
+
+if __name__ == "__main__":
+    try:
+        extra_compile_args = sysconfig.get_config_var('CFLAGS').split()
+    except AttributeError:
+        extra_compile_args = []
+
+    include_dirs = [np.get_include()]
+    pthread_flag = ["-pthread"] if os.name == 'posix' else []
+
+    brule_codec = setuptools.Extension(
+        f"{NAME}._brule",
+        sources=[f"src/{NAME}/rle/_brule.cc", f"src/{NAME}/rle/_librle.cc"],
+        include_dirs=include_dirs,
+        language="c",
+        extra_compile_args=extra_compile_args + pthread_flag,
+    )
+
+    layout_eng = setuptools.Extension(
+        f"{NAME}._layouteng",
+        sources=[f"src/{NAME}/layouteng/_layouteng.cc"],
+        include_dirs=include_dirs,
+        language="c",
+        extra_compile_args=extra_compile_args,
+    )
+
+    hextree = setuptools.Extension(
+        f"{NAME}._hextree",
+        sources=[f"src/{NAME}/hextree/_hextree.cc"],
+        include_dirs=include_dirs,
+        language="c",
+        extra_compile_args=extra_compile_args,
+    )
+
+    qtzrutc = setuptools.Extension(
+        f"{NAME}._qtzrutc",
+        sources=[f"src/{NAME}/qtzr/_qtzrutc.cc"],
+        include_dirs=include_dirs,
+        language="c",
+        extra_compile_args=extra_compile_args,
+    )
+
+    modules = [brule_codec, layout_eng, hextree, qtzrutc]
+
+    def run_setup(modules):
+        setuptools.setup(
+            cmdclass={"build_ext": ve_build_ext},
+            ext_modules=modules,
+        )
+    ####
+
+    try:
+        run_setup(modules)
+    except BuildFailed:
+        show_message(
+            "WARNING: Failed to compile optimised implementation."
+            "Retrying the build with only pure Python implementation.",
+        )
+        run_setup([])

brulegfx-0.0.6/src/brule/__init__.py

@@ -0,0 +1,30 @@
+"""
+MIT License
+
+Copyright (c) 2024 cubicibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from .__metadata__ import __version__, __author__
+
+from .brule import Brule
+from .layouteng import LayoutEngine
+from .hextree import HexTree
+from .qtzrutc import QtzrUTC

brulegfx-0.0.6/src/brule/__metadata__.py

@@ -0,0 +1,28 @@
+"""
+MIT License
+
+Copyright (c) 2024 cubicibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+__MAJOR, __MINOR, __REVISION = 0, 0, 6
+
+__version__ = '.'.join(map(str, [__MAJOR, __MINOR, __REVISION]))
+__author__ = 'cubicibo'

brulegfx-0.0.6/src/brule/brule.py

@@ -0,0 +1,247 @@
+"""
+MIT License
+
+Copyright (c) 2024 cubicibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from typing import Any, Callable, Optional, Union
+from dataclasses import dataclass
+
+import numpy as np
+from numpy import typing as npt
+
+@dataclass
+class _CodecFunctions:
+    encode: Callable[[npt.NDArray[np.uint8]], Union[bytes, bytearray]]
+    decode: Callable[[Union[bytes, bytearray]], npt.NDArray[np.uint8]]
+
+def _try_numba() -> _CodecFunctions:
+    #If numba is available, provide compiled functions for the encoder/decoder
+    from numba import njit
+
+    @njit(fastmath=True)
+    def njit_encode_rle(bitmap: npt.NDArray[np.uint8]) -> list[np.uint8]:
+        """
+        Encode a 2D map using the RLE defined in 'US 7912305 B1' patent.
+        :param bitmap:    Palette mapped image to encode (2d array)
+        :return:          Encoded data (vector)
+        """
+        i, j = 0, 0
+        rle_data = [np.uint8(x) for x in range(0)]
+
+        height, width = bitmap.shape
+        assert width <= 16383, "Bitmap too large."
+
+        while i < height:
+            color = bitmap[i, j]
+            prev_j = j
+            while (j := j+1) < width and bitmap[i, j] == color: pass
+
+            dist = j - prev_j
+            if color == 0:
+                if dist > 63:
+                    rle_data += [0x00, 0x40 | ((dist >> 8) & 0x3F), dist & 0xFF]
+                else:
+                    rle_data += [0x00, dist & 0x3F]
+            else:
+                if dist > 63:
+                    rle_data += [0x00, 0xC0 | ((dist >> 8) & 0x3F), dist & 0xFF, color]
+                elif dist > 2:
+                    rle_data += [0x00, 0x80 | (dist & 0x3F), color]
+                else:
+                    rle_data += [color] * dist
+            if j == width:
+                j = 0
+                i += 1
+                rle_data += [0x00, 0x00]
+        return rle_data
+
+    @njit(fastmath=True)
+    def njit_decode_rle(rle_data: Union[list[np.uint8], npt.NDArray[np.uint8], bytes], width: int, height: int, check_rle: bool = False) -> npt.NDArray[np.uint8]:
+        i, j, k = 0, -1, -2
+        # RLE is terminated by new line command ([0x00, 0x00]), we can ignore it.
+        len_rle = len(rle_data) - 2
+        bitmap = np.zeros((height, width), np.uint8)
+        line_length = 0
+
+        while k < len_rle:
+            if i % width == 0:
+                if line_length > 0:
+                    assert 0 == rle_data[k] == rle_data[k+1], "RLE line terminator not found at given width."
+                    assert not check_rle or line_length <= width, "Illegal RLE line width."
+                    line_length = 0
+                i = 0
+                j += 1
+                k += 2
+            k_start = k
+            byte = rle_data[k]
+            if byte == 0:
+                byte = rle_data[(k:=k+1)]
+                if byte & 0x40:
+                    length = ((byte & 0x3F) << 8) | rle_data[(k:=k+1)]
+                else:
+                    length = byte & 0x3F
+                if byte & 0x80:
+                    bitmap[j, i:(i:=i+length)] = rle_data[(k:=k+1)]
+                else:
+                    bitmap[j, i:(i:=i+length)] = 0
+            else:
+                bitmap[j, i:(i:=i+1)] = byte
+            k+=1
+            line_length += (k - k_start)
+        return bitmap
+    return _CodecFunctions(njit_encode_rle, njit_decode_rle)
+####
+
+#%%
+class Brule:
+    _numba_codec = None
+    _cimpl_codec = None
+
+    @classmethod
+    def _setup(cls) -> None:
+        try:
+            from . import _brule
+            cls._cimpl_codec = _CodecFunctions(_brule.encode, _brule.decode)
+        except (ImportError, ModuleNotFoundError): ...
+        try:
+            cls._numba_codec = _try_numba()
+        except (ImportError, ModuleNotFoundError): ...
+
+    @classmethod
+    def get_capabilities(cls) -> str:
+        cap  = ['C'] * (cls._cimpl_codec is not None)
+        cap += ['Numba'] * (cls._numba_codec is not None)
+        return cap + ['Python']
+
+    @classmethod
+    def _select_impl(cls, impl: str) -> bool:
+        impl = impl.tolower()
+        if impl == 'numba':
+            cls._setup()
+            cls._cimpl_codec = None
+            return cls._numba_codec is not None
+        if impl == 'python':
+            cls._cimpl_codec = None
+            cls._numba_codec = None
+            return True
+        if impl == 'c':
+            cls._setup()
+            return cls._cimpl_codec is not None
+        return False
+
+    @classmethod
+    def encode(cls, bitmap: npt.NDArray[np.uint8]) -> bytes:
+        """
+        Encode a 2D map using the RLE defined in 'US 7912305 B1' patent.
+        :param bitmap:    Palette mapped image to encode (2d array)
+        :return:          Encoded bytes (vector)
+        """
+        if cls._cimpl_codec is not None:
+            if not bitmap.flags['C_CONTIGUOUS']:
+                bitmap = np.ascontiguousarray(bitmap)
+            return cls._cimpl_codec.encode(bitmap)
+        if cls._numba_codec is not None:
+            return cls._numba_codec.encode(bitmap)
+
+        rle_data = []
+        i, j = 0, 0
+
+        height, width = bitmap.shape
+        assert width <= 16383, "Bitmap too large."
+
+        while i < height:
+            color = bitmap[i, j]
+            prev_j = j
+            while (j := j+1) < width and bitmap[i, j] == color: pass
+
+            dist = j - prev_j
+            if color == 0:
+                if dist > 63:
+                    rle_data += [0x00, 0x40 | ((dist >> 8) & 0x3F), dist & 0xFF]
+                else:
+                    rle_data += [0x00, dist & 0x3F]
+            else:
+                if dist > 63:
+                    rle_data += [0x00, 0xC0 | ((dist >> 8) & 0x3F), dist & 0xFF, color]
+                elif dist > 2:
+                    rle_data += [0x00, 0x80 | (dist & 0x3F), color]
+                else:
+                    rle_data += [color] * dist
+            if j == width:
+                j = 0
+                i += 1
+                rle_data += [0x00, 0x00]
+        return bytes(rle_data)
+
+    @classmethod
+    def decode(cls, data: Union[bytes, bytearray], width: Optional[int] = None, height: Optional[int] = None, check_rle: bool = False) -> npt.NDArray[np.uint8]:
+        """
+        Decode a RLE object, as defined in 'US 7912305 B1' patent.
+        :param data:  Bytes to decode
+        :return: numpy bitmap
+        """
+        if isinstance(data, list):
+            data = bytearray(data)
+
+        if cls._cimpl_codec is not None and check_rle is False:
+            return cls._cimpl_codec.decode(data)
+        if cls._numba_codec is not None and width and height:
+            return cls._numba_codec.decode(np.frombuffer(data, dtype=np.uint8), width, height, check_rle)
+
+        if check_rle:
+            assert width is not None and width > 0
+
+        k = 0
+        len_data = len(data)
+        bitmap = []
+        line = []
+        rle_line_length = 0
+
+        while k < len_data:
+            k_start = k
+            byte = data[k]
+            if byte == 0:
+                byte = data[(k:=k+1)]
+                if byte == 0:
+                    assert not check_rle or rle_line_length <= width
+                    bitmap.append(line)
+                    line = []
+                    rle_line_length = 0
+                    k += 1
+                    continue
+                if byte & 0x40:
+                    length = ((byte & 0x3F) << 8) | data[(k:=k+1)]
+                else:
+                    length = byte & 0x3F
+                if byte & 0x80:
+                    line += [data[(k:=k+1)]]*length
+                else:
+                    line += [0]*length
+            else:
+                line.append(byte)
+            k+=1
+            rle_line_length += (k - k_start)
+        return np.asarray(bitmap, np.uint8)
+####
+
+#init module
+Brule._setup()