plotille 6.0.0__py3-none-any.whl

plotille/__init__.py

@@ -0,0 +1,41 @@
+# The MIT License
+
+# Copyright (c) 2017 - 2025 Tammo Ippen, tammo.ippen@posteo.de
+
+# 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 ._canvas import Canvas
+from ._cmaps import Colormap, ListedColormap
+from ._colors import color, hsl
+from ._figure import Figure
+from ._graphs import hist, hist_aggregated, histogram, plot, scatter
+
+__all__ = [
+    "Canvas",
+    "Colormap",
+    "Figure",
+    "ListedColormap",
+    "color",
+    "hist",
+    "hist_aggregated",
+    "histogram",
+    "hsl",
+    "plot",
+    "scatter",
+]

plotille/_canvas.py

@@ -0,0 +1,443 @@
+# The MIT License
+
+# Copyright (c) 2017 - 2025 Tammo Ippen, tammo.ippen@posteo.de
+
+# 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
+from collections.abc import Sequence
+from typing import Any, Union
+
+from ._colors import MAX_RGB, RGB_VALUES, ColorDefinition, RGB_t, rgb2byte
+from ._dots import Dots
+from ._util import roundeven
+
+DotCoord = int
+RefCoord = Union[float, int]
+
+
+class Canvas:
+    """A canvas object for plotting braille dots
+
+    A Canvas object has a `width` x `height` characters large canvas, in which it
+    can plot indivitual braille point, lines out of braille points, rectangles,...
+    Since a full braille character has 2 x 4 dots (⣿), the canvas has `width` * 2,
+    `height` * 4 dots to plot into in total.
+
+    It maintains two coordinate systems: a reference system with the limits (xmin, ymin)
+    in the lower left corner to (xmax, ymax) in the upper right corner is transformed
+    into the canvas discrete, i.e. dots, coordinate system (0, 0) to (`width` * 2,
+    `height` * 4). It does so transparently to clients of the Canvas, i.e. all plotting
+    functions only accept coordinates in the reference system. If the coordinates are
+    outside the reference system, they are not plotted.
+    """
+
+    def __init__(
+        self,
+        width: DotCoord,
+        height: DotCoord,
+        xmin: RefCoord = 0,
+        ymin: RefCoord = 0,
+        xmax: RefCoord = 1,
+        ymax: RefCoord = 1,
+        background: ColorDefinition = None,
+        **color_kwargs: Any,
+    ) -> None:
+        """Initiate a Canvas object
+
+        Parameters:
+            width: int            The number of characters for the width (columns) of
+                                  the canvas.
+            height: int           The number of characters for the hight (rows) of the
+                                  canvas.
+            xmin, ymin: float     Lower left corner of reference system.
+            xmax, ymax: float     Upper right corner of reference system.
+            background: multiple  Background color of the canvas.
+            **color_kwargs:       More arguments to the color-function.
+                                  See `plotille.color()`.
+
+        Returns:
+            Canvas object
+        """
+        assert isinstance(width, int), "`width` has to be of type `int`"
+        assert isinstance(height, int), "`height` has to be of type `int`"
+        assert width > 0, "`width` has to be greater than 0"
+        assert height > 0, "`height` has to be greater than 0"
+        assert isinstance(xmin, (int, float))
+        assert isinstance(xmax, (int, float))
+        assert isinstance(ymin, (int, float))
+        assert isinstance(ymax, (int, float))
+        assert xmin < xmax, f"xmin ({xmin}) has to be smaller than xmax ({xmax})"
+        assert ymin < ymax, f"ymin ({ymin}) has to be smaller than ymax ({ymax})"
+
+        # characters in X / Y direction
+        self._width = width
+        self._height = height
+        # the X / Y limits of the canvas, i.e. (0, 0) in canvas is (xmin,ymin) and
+        # (width-1, height-1) in canvas is (xmax, ymax)
+        self._xmin = xmin
+        self._xmax = xmax
+        self._ymin = ymin
+        self._ymax = ymax
+        # value of x/y between one point
+        self._x_delta_pt = abs((xmax - xmin) / (width * 2))
+        self._y_delta_pt = abs((ymax - ymin) / (height * 4))
+        # the canvas to print in
+        self._color_mode = color_kwargs.get("mode", "names")
+        self._canvas = [
+            [Dots(bg=background, **color_kwargs) for j_ in range(width)]
+            for i_ in range(height)
+        ]
+
+    def __str__(self) -> str:
+        return f"Canvas(width={self.width}, height={self.height}, xmin={self.xmin}, ymin={self.ymin}, xmax={self.xmax}, ymax={self.ymax})"
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    @property
+    def width(self) -> int:
+        """Number of characters in X direction"""
+        return self._width
+
+    @property
+    def height(self) -> int:
+        """Number of characters in Y direction"""
+        return self._height
+
+    @property
+    def xmin(self) -> RefCoord:
+        """Get xmin coordinate of reference coordinate system [including]."""
+        return self._xmin
+
+    @property
+    def ymin(self) -> RefCoord:
+        """Get ymin coordinate of reference coordinate system [including]."""
+        return self._ymin
+
+    @property
+    def xmax(self) -> RefCoord:
+        """Get xmax coordinate of reference coordinate system [excluding]."""
+        return self._xmax
+
+    @property
+    def xmax_inside(self) -> float:
+        "Get max x-coordinate of reference coordinate system still inside the canvas."
+        return self.xmin + (self.width * 2 - 1) * self._x_delta_pt
+
+    @property
+    def ymax(self) -> RefCoord:
+        """Get ymax coordinate of reference coordinate system [excluding]."""
+        return self._ymax
+
+    @property
+    def ymax_inside(self) -> float:
+        "Get max y-coordinate of reference coordinate system still inside the canvas."
+        return self.ymin + (self.height * 4 - 1) * self._y_delta_pt
+
+    def _transform_x(self, x: RefCoord) -> DotCoord:
+        return int(roundeven((x - self.xmin) / self._x_delta_pt))
+
+    def _transform_y(self, y: RefCoord) -> DotCoord:
+        return int(roundeven((y - self.ymin) / self._y_delta_pt))
+
+    def _set(
+        self,
+        x_idx: int,
+        y_idx: int,
+        set_: bool = True,
+        color: ColorDefinition = None,
+        marker: str | None = None,
+    ) -> None:
+        """Put a dot into the canvas at (x_idx, y_idx) [canvas coordinate system]
+
+        Parameters:
+            x: int           x-coordinate on canvas.
+            y: int           y-coordinate on canvas.
+            set_: bool       Whether to plot or remove the point.
+            color: multiple  Color of the point.
+            marker: str      Instead of braille dots set a marker char.
+        """
+        x_c, x_p = x_idx // 2, x_idx % 2
+        y_c, y_p = y_idx // 4, y_idx % 4
+
+        if 0 <= x_c < self.width and 0 <= y_c < self.height:
+            self._canvas[y_c][x_c].update(x_p, y_p, set_, marker)
+            if color:
+                if set_:
+                    self._canvas[y_c][x_c].fg = color
+                elif color == self._canvas[y_c][x_c].fg:
+                    self._canvas[y_c][x_c].fg = None
+
+    def dots_between(
+        self, x0: RefCoord, y0: RefCoord, x1: RefCoord, y1: RefCoord
+    ) -> tuple[DotCoord, DotCoord]:
+        """Number of dots between (x0, y0) and (x1, y1).
+
+        Parameters:
+            x0, y0: float  Point 0
+            x1, y1: float  Point 1
+
+        Returns:
+            (int, int): dots in (x, y) direction
+        """
+        x0_idx = self._transform_x(x0)
+        y0_idx = self._transform_y(y0)
+        x1_idx = self._transform_x(x1)
+        y1_idx = self._transform_y(y1)
+
+        return x1_idx - x0_idx, y1_idx - y0_idx
+
+    def text(
+        self,
+        x: RefCoord,
+        y: RefCoord,
+        text: str,
+        set_: bool = True,
+        color: ColorDefinition = None,
+    ) -> None:
+        """Put some text into the canvas at (x, y) [reference coordinate system]
+
+        Parameters:
+            x: float         x-coordinate on reference system.
+            y: float         y-coordinate on reference system.
+            set_: bool       Whether to set the text or clear the characters.
+            text: str        The text to add.
+            color: multiple  Color of the point.
+        """
+        x_idx = self._transform_x(x) // 2
+        y_idx = self._transform_y(y) // 4
+
+        for idx in range(self.width - x_idx):
+            if text is None or len(text) <= idx:
+                break
+            val: str | None = text[idx]
+            if not set_:
+                val = None
+            self._canvas[y_idx][x_idx + idx].marker = val
+            if color:
+                if set_:
+                    self._canvas[y_idx][x_idx + idx].fg = color
+                elif color == self._canvas[y_idx][x_idx + idx].fg:
+                    self._canvas[y_idx][x_idx + idx].fg = None
+
+    def point(
+        self,
+        x: RefCoord,
+        y: RefCoord,
+        set_: bool = True,
+        color: ColorDefinition = None,
+        marker: str | None = None,
+    ) -> None:
+        """Put a point into the canvas at (x, y) [reference coordinate system]
+
+        Parameters:
+            x: float         x-coordinate on reference system.
+            y: float         y-coordinate on reference system.
+            set_: bool       Whether to plot or remove the point.
+            color: multiple  Color of the point.
+            marker: str      Instead of braille dots set a marker char.
+        """
+        x_idx = self._transform_x(x)
+        y_idx = self._transform_y(y)
+        self._set(x_idx, y_idx, set_, color, marker)
+
+    def fill_char(self, x: RefCoord, y: RefCoord, set_: bool = True) -> None:
+        """Fill the complete character at the point (x, y) [reference coordinate system]
+
+        Parameters:
+            x: float    x-coordinate on reference system.
+            y: float    y-coordinate on reference system.
+            set_: bool  Whether to plot or remove the point.
+        """
+        x_idx = self._transform_x(x)
+        y_idx = self._transform_y(y)
+
+        x_c = x_idx // 2
+        y_c = y_idx // 4
+
+        if set_:
+            self._canvas[y_c][x_c].fill()
+        else:
+            self._canvas[y_c][x_c].clear()
+
+    def line(
+        self,
+        x0: RefCoord,
+        y0: RefCoord,
+        x1: RefCoord,
+        y1: RefCoord,
+        set_: bool = True,
+        color: ColorDefinition = None,
+    ) -> None:
+        """Plot line between point (x0, y0) and (x1, y1) [reference coordinate system].
+
+        Parameters:
+            x0, y0: float    Point 0
+            x1, y1: float    Point 1
+            set_: bool       Whether to plot or remove the line.
+            color: multiple  Color of the line.
+        """
+        x0_idx = self._transform_x(x0)
+        y0_idx = self._transform_y(y0)
+        self._set(x0_idx, y0_idx, set_, color)
+
+        x1_idx = self._transform_x(x1)
+        y1_idx = self._transform_y(y1)
+        self._set(x1_idx, y1_idx, set_, color)
+
+        x_diff = x1_idx - x0_idx
+        y_diff = y1_idx - y0_idx
+        steps = max(abs(x_diff), abs(y_diff))
+        for i in range(1, steps):
+            xb = x0_idx + int(roundeven(x_diff / steps * i))
+            yb = y0_idx + int(roundeven(y_diff / steps * i))
+            self._set(xb, yb, set_, color)
+
+    def rect(
+        self,
+        xmin: RefCoord,
+        ymin: RefCoord,
+        xmax: RefCoord,
+        ymax: RefCoord,
+        set_: bool = True,
+        color: ColorDefinition = None,
+    ) -> None:
+        """Plot rectangle with bbox (xmin, ymin) and (xmax, ymax).
+
+        In the reference coordinate system.
+
+        Parameters:
+            xmin, ymin: float  Lower left corner of rectangle.
+            xmax, ymax: float  Upper right corner of rectangle.
+            set_: bool         Whether to plot or remove the rect.
+            color: multiple    Color of the rect.
+        """
+        assert xmin <= xmax
+        assert ymin <= ymax
+        self.line(xmin, ymin, xmin, ymax, set_, color)
+        self.line(xmin, ymax, xmax, ymax, set_, color)
+        self.line(xmax, ymax, xmax, ymin, set_, color)
+        self.line(xmax, ymin, xmin, ymin, set_, color)
+
+    def braille_image(
+        self,
+        pixels: Sequence[int],
+        threshold: int = 127,
+        inverse: bool = False,
+        color: ColorDefinition = None,
+        set_: bool = True,
+    ) -> None:
+        """Print an image using braille dots into the canvas.
+
+        The pixels and braille dots in the canvas are a 1-to-1 mapping, hence
+        a 80 x 80 pixel image will need a 40 x 20 canvas.
+
+        Example:
+            from PIL import Image
+            import plotille as plt
+
+            img = Image.open("/path/to/image")
+            img = img.convert('L')
+            img = img.resize((80, 80))
+            cvs = plt.Canvas(40, 20)
+            cvs.braille_image(img.getdata(), 125)
+            print(cvs.plot())
+
+        Parameters:
+            pixels: list[number]  All pixels of the image in one list.
+            threshold: float      All pixels above this threshold will be
+                                  drawn.
+            inverse: bool         Whether to invert the image.
+            color: multiple       Color of the point.
+            set_: bool            Whether to plot or remove the dots.
+        """
+        assert len(pixels) == self.width * 2 * self.height * 4
+        row_size = self.width * 2
+
+        for idx, value in enumerate(pixels):
+            do_dot = value >= threshold
+            if inverse:
+                do_dot = not do_dot
+            if not do_dot:
+                continue
+            y = self.height * 4 - idx // row_size - 1
+            x = idx % row_size
+
+            self._set(x, y, color=color, set_=set_)
+
+    def image(self, pixels: Sequence[RGB_t | None], set_: bool = True) -> None:
+        """Print an image using background colors into the canvas.
+
+        The pixels of the image and the characters in the canvas are a
+        1-to-1 mapping, hence a 80 x 80 image will need a 80 x 80 canvas.
+
+        Example:
+            from PIL import Image
+            import plotille as plt
+
+            img = Image.open("/path/to/image")
+            img = img.convert('RGB')
+            img = img.resize((40, 40))
+            cvs = plt.Canvas(40, 40, mode='rgb')
+            cvs.image(img.getdata())
+            print(cvs.plot())
+
+        Parameters:
+            pixels: list[(R,G,B)]  All pixels of the image in one list.
+            set_: bool             Whether to plot or remove the background
+                                   colors.
+        """
+        assert len(pixels) == self.width * self.height
+
+        for idx, values in enumerate(pixels):
+            if values is None:
+                continue
+            # RGB
+            assert len(values) == RGB_VALUES
+            assert all(0 <= v <= MAX_RGB for v in values)
+
+            y = self.height - idx // self.width - 1
+            x = idx % self.width
+
+            color_value: ColorDefinition
+            if set_ is False:
+                color_value = None
+            elif self._color_mode == "rgb":
+                color_value = values
+            elif self._color_mode == "byte":
+                color_value = rgb2byte(*values)
+            else:
+                raise NotImplementedError(
+                    "Only color_modes rgb and byte are supported."
+                )
+
+            self._canvas[y][x].bg = color_value
+
+    def plot(self, linesep: str = os.linesep) -> str:
+        """Transform canvas into `print`-able string
+
+        Parameters:
+            linesep: str  The requested line separator. default: os.linesep
+
+        Returns:
+            unicode: The canvas as a string.
+        """
+
+        return linesep.join("".join(map(str, row)) for row in reversed(self._canvas))

plotille/_cmaps.py

@@ -0,0 +1,124 @@
+# The MIT License
+
+# Copyright (c) 2017 - 2025 Tammo Ippen, tammo.ippen@posteo.de
+
+# 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 math
+from collections.abc import Sequence
+
+from . import _cmaps_data
+
+Number = float | int
+
+
+class Colormap:
+    """
+    Baseclass for all scalar to RGB mappings.
+
+    Typically, Colormap instances are used to convert data values (floats)
+    from the interval `[0, 1]` to the RGB color that the respective
+    Colormap represents. Scaling the data into the `[0, 1]` interval is
+    responsibility of the caller.
+    """
+
+    def __init__(self, name: str, lookup_table: Sequence[Sequence[float]]) -> None:
+        """
+        Parameters
+        ----------
+        name : str
+            The name of the colormap.
+        N : int
+            The number of rgb quantization levels.
+        """
+        self.name: str = name
+        self._lookup_table: Sequence[Sequence[float]] = lookup_table
+        self.bad: Sequence[Number] | None = None
+        self.over: Sequence[Number] | None = None
+        self.under: Sequence[Number] | None = None
+
+    def __call__(
+        self, X: Number | Sequence[Number]
+    ) -> Sequence[Number] | list[Sequence[Number] | None] | None:
+        """
+        Parameters
+        ----------
+        X : float or iterable of floats
+            The data value(s) to convert to RGB.
+            For floats, X should be in the interval `[0.0, 1.0]` to
+            return the RGB values `X*100` percent along the Colormap line.
+
+        Returns
+        -------
+        Tuple of RGB values if X is scalar, otherwise an array of
+        RGB values with a shape of `X.shape + (3, )`.
+        """
+        try:
+            return [self._process_value(x) for x in X]  # type: ignore [union-attr]
+        except TypeError:
+            # not iterable
+            assert isinstance(X, (int, float))
+            return self._process_value(X)
+
+    def _process_value(self, x: Number) -> Sequence[Number] | None:
+        if not isinstance(x, (int, float)) or math.isnan(x) or math.isinf(x):
+            return self.bad
+        if x < 0:
+            return self.under
+        if x > 1:
+            return self.over
+        idx = round(x * (len(self._lookup_table) - 1))
+        return self._lookup_table[idx]
+
+
+class ListedColormap(Colormap):
+    def __init__(self, name: str, colors: Sequence[Sequence[int]]) -> None:
+        super().__init__(name, lookup_table=colors)
+
+    @classmethod
+    def from_relative(
+        cls, name: str, colors: Sequence[Sequence[float]]
+    ) -> "ListedColormap":
+        return cls(
+            name,
+            [(round(255 * r), round(255 * g), round(255 * b)) for r, g, b in colors],
+        )
+
+
+# Always generate a new cmap, such that you can override bad / over under values easily.
+cmaps = {}
+cmaps["magma"] = lambda: ListedColormap.from_relative("magma", _cmaps_data.magma_data)
+cmaps["inferno"] = lambda: ListedColormap.from_relative(
+    "inferno", _cmaps_data.inferno_data
+)
+cmaps["plasma"] = lambda: ListedColormap.from_relative(
+    "plasma", _cmaps_data.plasma_data
+)
+cmaps["viridis"] = lambda: ListedColormap.from_relative(
+    "viridis", _cmaps_data.viridis_data
+)
+cmaps["jet"] = lambda: ListedColormap.from_relative("jet", _cmaps_data.jet_data)
+cmaps["copper"] = lambda: ListedColormap.from_relative(
+    "copper", _cmaps_data.copper_data
+)
+cmaps["gray"] = lambda: ListedColormap(
+    name="gray", colors=[(idx, idx, idx) for idx in range(256)]
+)
+
+# for more, have a look at https://matplotlib.org/stable/tutorials/colors/colormaps.html