### Install Plotille

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Use pip to install the library.

```sh
pip install plotille
```

--------------------------------

### Image Rendering Example

Source: https://context7.com/tammoippen/plotille/llms.txt

Demonstrates how to load, prepare, and render an image onto a Plotille canvas using RGB mode.

```APIDOC
## Load and prepare image
img = Image.open('path/to/image.jpg')
img = img.convert('RGB')
img = img.resize((40, 40))       # Each pixel = one character

# Create canvas with RGB color mode
canvas = plotille.Canvas(40, 40, mode='rgb')

# Render image using background colors
canvas.image(img.getdata())

print(canvas.plot())
```

--------------------------------

### Datetime Support in Plotting

Source: https://context7.com/tammoippen/plotille/llms.txt

Illustrates how Plotille handles datetime values for X and Y axes, automatically formatting labels based on the time range. Examples include plotting a single series with dates and plotting multiple series (temperature and humidity) against time using the `Figure` class.

```APIDOC
## Datetime Support

### Plotting with Datetime Values

Plotille supports datetime values for both X and Y axes, automatically formatting labels based on the time range.

```python
from datetime import datetime, timedelta
import plotille

# Generate datetime series
start = datetime(2024, 1, 1)
dates = [start + timedelta(days=i) for i in range(30)]
values = [10 + 5 * (i % 7) + i * 0.5 for i in range(30)]

# Plot with datetime X-axis
print(plotille.plot(dates, values, height=15, width=60))

# Using Figure with datetime
fig = plotille.Figure()
fig.width = 60
fig.height = 20

# Multiple series with datetime
dates2 = [start + timedelta(hours=i) for i in range(48)]
temp = [20 + 5 * (1 + 0.5 * ((i % 24) - 12) / 12) for i in range(48)]
humidity = [60 + 10 * (1 - 0.3 * ((i % 24) - 12) / 12) for i in range(48)]

fig.plot(dates2, temp, lc='red', label='Temperature')
fig.plot(dates2, humidity, lc='blue', label='Humidity')

print(fig.show(legend=True))
```
```

--------------------------------

### Plotting with Datetime Axes in Plotille

Source: https://context7.com/tammoippen/plotille/llms.txt

Plotille automatically handles datetime objects for X and Y axes, formatting labels appropriately. Examples show plotting a single series with a datetime X-axis and multiple series using the `Figure` class, including a legend.

```python
from datetime import datetime, timedelta
import plotille

# Generate datetime series
start = datetime(2024, 1, 1)
dates = [start + timedelta(days=i) for i in range(30)]
values = [10 + 5 * (i % 7) + i * 0.5 for i in range(30)]

# Plot with datetime X-axis
print(plotille.plot(dates, values, height=15, width=60))

# Using Figure with datetime
fig = plotille.Figure()
fig.width = 60
fig.height = 20

# Multiple series with datetime
dates2 = [start + timedelta(hours=i) for i in range(48)]
temp = [20 + 5 * (1 + 0.5 * ((i % 24) - 12) / 12) for i in range(48)]
humidity = [60 + 10 * (1 - 0.3 * ((i % 24) - 12) / 12) for i in range(48)]

fig.plot(dates2, temp, lc='red', label='Temperature')
fig.plot(dates2, humidity, lc='blue', label='Humidity')

print(fig.show(legend=True))
```

--------------------------------

### Initialize Plotille Environment

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Import the library and prepare sample data using numpy.

```python
In [1]: import plotille
In [2]: import numpy as np
In [3]: X = np.sort(np.random.normal(size=1000))
```

--------------------------------

### Initialize Canvas

Source: https://context7.com/tammoippen/plotille/llms.txt

Creates a Canvas instance for low-level drawing with custom coordinate systems.

```python
import plotille

# Create a canvas with 40x20 characters
# Each character has 2x4 braille dots, so 80x80 dots total
canvas = plotille.Canvas(width=40, height=20)

# Default coordinate system is (0,0) to (1,1)
# Custom coordinate system
canvas2 = plotille.Canvas(
    width=40,
    height=20,
    xmin=0,
    ymin=0,
    xmax=100,
    ymax=100,
    background='black',
    mode='names'
)

print(canvas)  # Canvas(width=40, height=20, xmin=0, ymin=0, xmax=1, ymax=1)
```

--------------------------------

### Figure Class Initialization and Properties

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Demonstrates how to initialize a Figure object and set its properties like dimensions, limits, color mode, and labels.

```APIDOC
## Figure Class

### Description

The `Figure` class is used to compose multiple plots within a single terminal output. It allows for defining the canvas size, data limits, color modes, and axis labels.

### Init Signature

`plotille.Figure()`

### Properties

- **width** (int) - Defines the number of characters in the X direction for plotting.
- **height** (int) - Defines the number of characters in the Y direction for plotting.
- **x_limits** (DataValue) - Defines the X limits of the reference coordinate system.
- **y_limits** (DataValue) - Defines the Y limits of the reference coordinate system.
- **color_mode** (str) - Defines the used color mode (e.g., 'byte').
- **with_colors** (bool) - Defines whether to use colors.
- **background** (ColorDefinition) - Defines the background color.
- **x_label** (str) - Defines the X-axis label.
- **y_label** (str) - Defines the Y-axis label.

### Example Usage

```python
import plotille
import numpy as np

fig = plotille.Figure()
fig.width = 60
fig.height = 30
fig.set_x_limits(min_=-3, max_=3)
fig.set_y_limits(min_=-1, max_=1)
fig.color_mode = 'byte'
```
```

--------------------------------

### Initialize plotille.Canvas

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Instantiate a Canvas object with specified dimensions and coordinate system limits. Optional background color can be set.

```python
plotille.Canvas(
    width: int,
    height: int,
    xmin: Union[float, int] = 0,
    ymin: Union[float, int] = 0,
    xmax: Union[float, int] = 1,
    ymax: Union[float, int] = 1,
    background: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    **color_kwargs: Any,
) -> None
```

--------------------------------

### Create a Figure and Add Multiple Plots

Source: https://context7.com/tammoippen/plotille/llms.txt

Initializes a Figure object, sets dimensions and axis limits, configures color mode, and adds multiple line plots (sine and cosine) along with scatter samples. Requires 'numpy' and 'plotille'.

```python
import numpy as np
import plotille

# Create a new figure
fig = plotille.Figure()

# Set dimensions
fig.width = 60
fig.height = 30

# Set axis limits
fig.set_x_limits(min_=-3, max_=3)
fig.set_y_limits(min_=-1.5, max_=1.5)

# Set labels
fig.x_label = 'X Axis'
fig.y_label = 'Y Axis'

# Configure color mode ('names', 'byte', or 'rgb')
fig.color_mode = 'byte'

# Add multiple plots
x = np.linspace(-3, 3, 100)
fig.plot(x, np.sin(x), lc=196, label='sin(x)')      # Red
fig.plot(x, np.cos(x), lc=46, label='cos(x)')       # Green
fig.scatter(x[::10], np.sin(x[::10]), lc=226, label='samples')  # Yellow points

# Show with legend
print(fig.show(legend=True))
```

--------------------------------

### Compose and Display a Figure

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Configure a Figure instance, add plots, and render the output.

```python
In [13] fig = plotille.Figure()
In [14] fig.width = 60
In [15] fig.height = 30
In [16] fig.set_x_limits(min_=-3, max_=3)
In [17] fig.set_y_limits(min_=-1, max_=1)
In [18] fig.color_mode = 'byte'
In [19] fig.plot([-0.5, 1], [-1, 1], lc=25, label='First line')
In [20] fig.scatter(X, np.sin(X), lc=100, label='sin')
In [21] fig.plot(X, (X+2)**2 , lc=200, label='square')
In [22] print(fig.show(legend=True))
```

--------------------------------

### Canvas Initialization

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Initializes a new Canvas object with specified dimensions and coordinate limits.

```APIDOC
## Canvas Initialization

### Description
Creates a new canvas object for plotting braille dots within a defined coordinate system.

### Parameters
- **width** (int) - Required - Number of characters for the width.
- **height** (int) - Required - Number of characters for the height.
- **xmin, ymin** (float) - Optional - Lower left corner of reference system.
- **xmax, ymax** (float) - Optional - Upper right corner of reference system.
- **background** (multiple) - Optional - Background color of the canvas.
```

--------------------------------

### Create Standard Histogram with Plotille

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Use `histogram` for raw data to generate a frequency distribution. Customize the number of bins and dimensions for the output.

```python
In [10]: plotille.histogram?
Signature:
plotille.histogram(
    X: Sequence[float | int] | Sequence[datetime.datetime],
    bins: int = 160,
    width: int = 80,
    height: int = 40,
    X_label: str = 'X',
    Y_label: str = 'Counts',
    linesep: str = '\n',
    x_min: float | int | datetime.datetime | None = None,
    x_max: float | int | datetime.datetime | None = None,
    y_min: float | int | datetime.datetime | None = None,
    y_max: float | int | datetime.datetime | None = None,
    lc: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    bg: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    color_mode: Literal['names', 'byte', 'rgb'] = 'names',
)
Docstring:
Create histogram over `X`

In contrast to `hist`, this is the more `usual` histogram from bottom
to up. The X-axis represents the values in `X` and the Y-axis is the
corresponding frequency.

Parameters:
    X: List[float]       The items to count over.
    bins: int            The number of bins to put X entries in (columns).
    height: int          The number of characters for the height (rows).
    X_label: str         Label for X-axis.
    Y_label: str         Label for Y-axis. max 8 characters.
    linesep: str         The requested line separator. default: os.linesep
    x_min, x_max: float  Limits for the displayed X values.
    y_min, y_max: float  Limits for the displayed Y values.
    lc: ColorDefinition         Give the line color.
    bg: ColorDefinition         Give the background color.
    color_mode: ColorMode      Specify color input mode; 'names' (default), 'byte' or
                         'rgb' see plotille.color.__docs__

Returns:
    str: histogram over `X`.

In [11]: print(plotille.histogram(np.random.normal(size=10000)))
```

--------------------------------

### Display Image Data as Heatmap

Source: https://context7.com/tammoippen/plotille/llms.txt

Displays image data as a heatmap using colormaps. Supports scalar data mapped through colormaps or RGB data. Requires 'plotille'.

```python
import plotille
```

--------------------------------

### Render Image with Plotille

Source: https://context7.com/tammoippen/plotille/llms.txt

Renders an image to the terminal using plotille. Requires Pillow for image manipulation. Ensure the image is converted to RGB and resized appropriately.

```python
from PIL import Image
import plotille

# Load and prepare image
img = Image.open('path/to/image.jpg')
img = img.convert('RGB')
img = img.resize((40, 40))       # Each pixel = one character

# Create canvas with RGB color mode
canvas = plotille.Canvas(40, 40, mode='rgb')

# Render image using background colors
canvas.image(img.getdata())

print(canvas.plot())
```

--------------------------------

### Create a Histogram with Background Color

Source: https://context7.com/tammoippen/plotille/llms.txt

Generates a histogram with specified bins, dimensions, and custom colors for the plot elements and background. Requires 'plotille' library.

```python
import plotille

print(plotille.histogram(
    data,
    bins=100,
    width=70,
    height=30,
    lc=82,                 # Light green in byte mode
    bg=236,                # Dark gray
    color_mode='byte'
))
```

--------------------------------

### Basic Line Plot with plotille.plot

Source: https://context7.com/tammoippen/plotille/llms.txt

Creates a basic line plot using linear interpolation between data points. Requires numpy for data generation and plotille for plotting.

```python
import numpy as np
import plotille

# Create sample data
x = np.linspace(0, 2 * np.pi, 50)
y = np.sin(x)

# Basic plot with linear interpolation
print(plotille.plot(x, y, height=20, width=60))
```

--------------------------------

### Canvas.image

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Renders an image onto the canvas using background colors of characters. The image dimensions should match the canvas dimensions for a 1-to-1 mapping.

```APIDOC
## Canvas.image

### Description
Renders an image onto the canvas using background colors of characters. The image dimensions should match the canvas dimensions for a 1-to-1 mapping.

### Method
`Canvas.image`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pixels** (Sequence[tuple[int, int, int] | Sequence[int] | None]) - Required - All pixels of the image in one list. Expects RGB tuples or lists.
- **set_** (bool) - Optional - Whether to plot or remove the background colors. Default is True.

### Request Example
```python
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())
```

### Response
#### Success Response (200)
None (This method modifies the canvas in place)

#### Response Example
None
```

--------------------------------

### Render a Color Image

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Maps image pixels to canvas background colors using an RGB mode canvas.

```python
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())
```

```python
In [24]: img = Image.open('https://github.com/tammoippen/plotille/raw/master/imgs/ich.jpg')
In [25]: img = img.convert('RGB')
In [25]: img = img.resize((80, 40))
In [27]: cvs = Canvas(80, 40, mode="rgb")
In [28]: cvs.image(img.getdata())
In [29]: print(cvs.plot())
```

--------------------------------

### Render Braille Image

Source: https://context7.com/tammoippen/plotille/llms.txt

Converts grayscale image data into a braille-based terminal representation.

```python
from PIL import Image
import plotille

# Load and prepare image
img = Image.open('path/to/image.jpg')
img = img.convert('L')           # Convert to grayscale
img = img.resize((80, 80))       # 80x80 pixels = 40x20 canvas (2x4 dots per char)

# Create canvas matching image dimensions
canvas = plotille.Canvas(40, 20)

# Render image with braille dots
canvas.braille_image(
    img.getdata(),
    threshold=127,               # Pixels above threshold are drawn
    inverse=False,               # Set True to invert
    color='white'
)

print(canvas.plot())
```

--------------------------------

### Create Histogram with Plotille

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Use plotille.hist to generate a histogram from a sequence of values. Control the number of bins and the width of the plot. Supports logarithmic scaling for the histogram.

```python
print(plotille.hist(np.random.normal(size=10000)))
```

--------------------------------

### plotille.hsl - HSL to RGB Conversion

Source: https://context7.com/tammoippen/plotille/llms.txt

Explains the `plotille.hsl` function, which converts HSL (Hue, Saturation, Lightness) color values to RGB tuples. This is useful for generating colors programmatically, especially for use with the RGB color mode in `plotille.color` or for creating color gradients.

```APIDOC
### plotille.hsl

Converts HSL (Hue, Saturation, Lightness) color values to RGB tuples for use with RGB color mode.

```python
import plotille

# Convert HSL to RGB
red = plotille.hsl(0, 1.0, 0.5)        # (255, 0, 0)
green = plotille.hsl(120, 1.0, 0.5)    # (0, 255, 0)
blue = plotille.hsl(240, 1.0, 0.5)     # (0, 0, 255)

# Use in plots
print(plotille.color('HSL Red', fg=red, mode='rgb'))
print(plotille.color('HSL Green', fg=green, mode='rgb'))

# Create color gradient
for hue in range(0, 360, 30):
    rgb = plotille.hsl(hue, 1.0, 0.5)
    print(plotille.color(f'Hue {hue:3d}', fg=rgb, mode='rgb'))
```
```

--------------------------------

### Render a Braille Image

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Converts a grayscale image into a braille-based representation on a canvas.

```python
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())
```

```python
In [24]: img = Image.open('https://github.com/tammoippen/plotille/raw/master/imgs/ich.jpg')
In [25]: img = img.convert('L')
In [26]: img = img.resize((80, 80))
In [27]: cvs = Canvas(40, 20)
In [28]: cvs.braille_image(img.getdata())
In [29]: print(cvs.plot())
```

--------------------------------

### Canvas Class

Source: https://context7.com/tammoippen/plotille/llms.txt

Provides low-level drawing primitives using braille characters for high-resolution dot-based rendering.

```APIDOC
## Canvas Class

### Description
Initializes a canvas for custom visualizations.

### Parameters
#### Request Body
- **width** (int) - Required - Width in characters.
- **height** (int) - Required - Height in characters.
- **xmin, ymin, xmax, ymax** (float) - Optional - Coordinate system bounds.
- **background** (string) - Optional - Background color.
- **mode** (string) - Optional - Rendering mode.
```

--------------------------------

### Canvas.text

Source: https://context7.com/tammoippen/plotille/llms.txt

Places text on the canvas.

```APIDOC
## Canvas.text

### Description
Places text at specified coordinates on the canvas.

### Parameters
#### Request Body
- **x, y** (float) - Required - Coordinates.
- **text** (string) - Required - The text string to display.
- **color** (string) - Optional - Color of the text.
```

--------------------------------

### Basic Horizontal Histogram with plotille.hist

Source: https://context7.com/tammoippen/plotille/llms.txt

Creates a horizontal histogram showing data frequency distribution. Bars extend from left to right, with bucket ranges on the left and counts on the right.

```python
import numpy as np
import plotille

# Generate normally distributed data
data = np.random.normal(0, 1, 10000)

# Basic histogram
print(plotille.hist(data))
```

--------------------------------

### Canvas Image Signature

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Displays the signature and docstring for the Canvas.image method.

```python
In [18]: plotille.Canvas.image?
Signature:
plotille.Canvas.image(
    self,
    pixels: Sequence[tuple[int, int, int] | Sequence[int] | None],
    set_: bool = True,
) -> None
Docstring:
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.
```

--------------------------------

### plotille.color - ANSI Escape Codes for Terminal Coloring

Source: https://context7.com/tammoippen/plotille/llms.txt

Explains how to use the `plotille.color` function to wrap text with ANSI escape codes for terminal coloring. It supports named colors (3/4-bit), byte (8-bit), and RGB (24-bit) color modes, as well as bright variants and conditional color disabling.

```APIDOC
## Color Functions

### plotille.color

Wraps text with ANSI escape codes for terminal coloring. Supports three color modes: names (3/4-bit), byte (8-bit), and rgb (24-bit).

```python
import plotille

# Named colors (3/4-bit mode)
print(plotille.color('Red text', fg='red'))
print(plotille.color('Blue background', bg='blue'))
print(plotille.color('Black on cyan', fg='black', bg='cyan'))

# Bright variants
print(plotille.color('Bright green', fg='bright_green'))

# 8-bit colors (256 color palette)
print(plotille.color('8-bit foreground', fg=196, mode='byte'))
print(plotille.color('8-bit both', fg=226, bg=17, mode='byte'))

# 24-bit RGB colors
print(plotille.color('RGB tuple', fg=(255, 128, 0), mode='rgb'))
print(plotille.color('RGB hex', fg='ff8000', bg='001122', mode='rgb'))

# Disable colors conditionally
print(plotille.color('No color', fg='red', no_color=True))

# Available named colors:
# black, red, green, yellow, blue, magenta, cyan, white
# bright_black, bright_red, bright_green, bright_yellow,
# bright_blue, bright_magenta, bright_cyan, bright_white
```
```

--------------------------------

### Figure Plot Method Signature

Source: https://github.com/tammoippen/plotille/blob/master/README.md

View the signature for the plot method.

```python
# create a plot with linear interpolation between points
Figure.plot(self, X, Y, lc=None, interp='linear', label=None, marker=None)
```

--------------------------------

### Render Braille Image on Canvas

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Plot an image onto the canvas using braille dots. The pixel grid maps directly to the braille dot grid. Supports thresholding and inversion.

```python
plotille.Canvas.braille_image(
    self,
    pixels: Sequence[int],
    threshold: int = 127,
    inverse: bool = False,
    color: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    set_: bool = True,
) -> None
```

--------------------------------

### Draw Lines on Canvas

Source: https://context7.com/tammoippen/plotille/llms.txt

Connects two points on the canvas using braille dot lines.

```python
import plotille

canvas = plotille.Canvas(width=40, height=20)

# Draw lines
canvas.line(0.1, 0.1, 0.9, 0.9, color='red')     # Diagonal
canvas.line(0.1, 0.9, 0.9, 0.1, color='blue')    # Other diagonal
canvas.line(0.5, 0.1, 0.5, 0.9, color='green')   # Vertical
canvas.line(0.1, 0.5, 0.9, 0.5, color='yellow')  # Horizontal

print(canvas.plot())
```

--------------------------------

### Access Figure Documentation

Source: https://github.com/tammoippen/plotille/blob/master/README.md

View the docstring for the Figure class.

```python
In [4]: plotille.Figure?
Init signature: plotille.Figure() -> None
Docstring:
Figure class to compose multiple plots.

Within a Figure you can easily compose many plots, assign labels to plots
and define the properties of the underlying Canvas. Possible properties that
can be defined are:

    width, height: int           Define the number of characters in X / Y direction
                                 which are used for plotting.
    x_limits: DataValue          Define the X limits of the reference coordinate system,
                                 that will be plotted.
    y_limits: DataValue          Define the Y limits of the reference coordinate system,
                                 that will be plotted.
    color_mode: str              Define the used color mode. See `plotille.color()`.
    with_colors: bool            Define, whether to use colors at all.
    background: ColorDefinition  Define the background color.
    x_label, y_label: str        Define the X / Y axis label.
```

--------------------------------

### Canvas.braille_image

Source: https://context7.com/tammoippen/plotille/llms.txt

Renders a grayscale image using braille dots.

```APIDOC
## Canvas.braille_image

### Description
Renders a grayscale image using braille dots where each pixel maps to one dot.

### Parameters
#### Request Body
- **data** (iterable) - Required - Image pixel data.
- **threshold** (int) - Optional - Threshold for drawing pixels.
- **inverse** (bool) - Optional - Invert the image.
- **color** (string) - Optional - Color of the dots.
```

--------------------------------

### Figure.imgshow

Source: https://context7.com/tammoippen/plotille/llms.txt

Displays 2D scalar data as a heatmap within a Figure object.

```APIDOC
## Figure.imgshow

### Description
Displays 2D scalar data as a heatmap. Supports various colormaps.

### Parameters
#### Request Body
- **data** (list of lists) - Required - 2D array of scalar values.
- **cmap** (string) - Optional - Colormap to use (e.g., 'magma', 'inferno', 'plasma', 'viridis', 'jet', 'copper', 'gray').

### Response
Returns a string representation of the heatmap for terminal display.
```

--------------------------------

### Canvas.point

Source: https://context7.com/tammoippen/plotille/llms.txt

Places a single point on the canvas.

```APIDOC
## Canvas.point

### Description
Places a single braille dot at specified coordinates.

### Parameters
#### Request Body
- **x, y** (float) - Required - Coordinates.
- **color** (string) - Optional - Color of the point.
- **marker** (string) - Optional - Custom marker character.
- **set_** (bool) - Optional - Whether to draw (True) or remove (False) the point.
```

--------------------------------

### Create 2D Heatmap with Figure

Source: https://context7.com/tammoippen/plotille/llms.txt

Generates a heatmap using the Figure class with specified colormaps.

```python
width, height = 40, 20
data = [[None for _ in range(width)] for _ in range(height)]

# Create a gradient pattern
for y in range(height):
    for x in range(width):
        # Normalize to 0-1 range for colormap
        data[y][x] = (x / width + y / height) / 2

fig = plotille.Figure()
fig.width = width
fig.height = height
fig.color_mode = 'byte'

# Display with plasma colormap
fig.imgshow(data, cmap='plasma')
print(fig.show())

# Available colormaps: 'magma', 'inferno', 'plasma', 'viridis', 'jet', 'copper', 'gray'

# Create another figure with different colormap
fig2 = plotille.Figure()
fig2.width = width
fig2.height = height
fig2.color_mode = 'byte'
fig2.imgshow(data, cmap='viridis')
print(fig2.show())
```

--------------------------------

### Colormap Classes - Colormap and ListedColormap

Source: https://context7.com/tammoippen/plotille/llms.txt

Details the `Colormap` and `ListedColormap` classes for mapping scalar values (0-1) to RGB colors. This is essential for visualizations like heatmaps and image rendering where data values need to be translated into visual colors. It covers using built-in colormaps and creating custom ones.

```APIDOC
## Colormap Classes

### Colormap and ListedColormap

Maps scalar values (0-1) to RGB colors for heatmaps and image visualization.

```python
import plotille
from plotille._cmaps import cmaps, ListedColormap

# Use built-in colormaps
plasma = cmaps['plasma']()
print(plasma(0.0))    # Returns RGB tuple for value 0
print(plasma(0.5))    # Returns RGB tuple for value 0.5
print(plasma(1.0))    # Returns RGB tuple for value 1

# Map multiple values
values = [0.0, 0.25, 0.5, 0.75, 1.0]
colors = plasma(values)  # Returns list of RGB tuples

# Available built-in colormaps
available_cmaps = ['magma', 'inferno', 'plasma', 'viridis', 'jet', 'copper', 'gray']

# Create custom colormap
custom_colors = [
    (0, 0, 255),      # Blue
    (0, 255, 255),    # Cyan
    (0, 255, 0),      # Green
    (255, 255, 0),    # Yellow
    (255, 0, 0),      # Red
]
custom_cmap = ListedColormap('custom', custom_colors)

# Set colors for out-of-range and invalid values
custom_cmap.bad = (128, 128, 128)    # Gray for NaN/invalid
custom_cmap.over = (255, 255, 255)   # White for > 1
custom_cmap.under = (0, 0, 0)        # Black for < 0
```
```

--------------------------------

### Canvas.rect

Source: https://context7.com/tammoippen/plotille/llms.txt

Draws a rectangle outline.

```APIDOC
## Canvas.rect

### Description
Draws a rectangle outline between two corner points.

### Parameters
#### Request Body
- **x0, y0** (float) - Required - First corner.
- **x1, y1** (float) - Required - Opposite corner.
- **color** (string) - Optional - Color of the rectangle.
```

--------------------------------

### Basic Vertical Histogram with plotille.histogram

Source: https://context7.com/tammoippen/plotille/llms.txt

Generates a traditional vertical histogram with X and Y axes. The X-axis represents values, and the Y-axis represents frequency counts.

```python
import numpy as np
import plotille

# Generate sample data
data = np.random.normal(0, 1, 10000)

# Basic vertical histogram
print(plotille.histogram(data))
```

--------------------------------

### Canvas.braille_image

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Renders an image onto the canvas using braille characters. The image is converted to grayscale and resized to match the canvas dimensions for a 1-to-1 pixel mapping.

```APIDOC
## Canvas.braille_image

### Description
Renders an image onto the canvas using braille characters. The image is converted to grayscale and resized to match the canvas dimensions for a 1-to-1 pixel mapping.

### Method
`Canvas.braille_image`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pixels** (list[number]) - Required - All pixels of the image in one list.
- **threshold** (float) - Optional - All pixels above this threshold will be drawn.
- **inverse** (bool) - Optional - Whether to invert the image.
- **color** (multiple) - Optional - Color of the point.
- **set_** (bool) - Optional - Whether to plot or remove the dots. Default is True.

### Request Example
```python
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())
```

### Response
#### Success Response (200)
None (This method modifies the canvas in place)

#### Response Example
None
```

--------------------------------

### Draw Points on Canvas

Source: https://context7.com/tammoippen/plotille/llms.txt

Places individual braille dots on the canvas with optional markers and colors.

```python
import plotille

canvas = plotille.Canvas(width=40, height=20)

# Draw points at various positions
canvas.point(0.2, 0.2, color='red')
canvas.point(0.5, 0.5, color='green')
canvas.point(0.8, 0.8, color='blue')

# Draw a point with custom marker
canvas.point(0.5, 0.2, color='yellow', marker='*')

# Remove a point (set_=False)
canvas.point(0.5, 0.5, set_=False)

print(canvas.plot())
```

--------------------------------

### Canvas Plotting Methods

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Methods for retrieving the string representation of the canvas and drawing geometric shapes.

```python
In [16]: plotille.Canvas.plot?Signature: plotille.Canvas.plot(self, linesep: str = '\n') -> strDocstring:Transform canvas into `print`-able stringParameters:    linesep: str  The requested line separator. default: os.linesepReturns:    unicode: The canvas as a string.
```

```python
In [17]: c = Canvas(width=40, height=20)
In [18]: c.rect(0.1, 0.1, 0.6, 0.6)
In [19]: c.line(0.1, 0.1, 0.6, 0.6)
In [20]: c.line(0.1, 0.6, 0.6, 0.1)
In [21]: c.line(0.1, 0.6, 0.35, 0.8)
In [22]: c.line(0.35, 0.8, 0.6, 0.6)
In [23]: print(c.plot())
```

--------------------------------

### Draw Rectangles on Canvas

Source: https://context7.com/tammoippen/plotille/llms.txt

Renders rectangle outlines between two specified corner coordinates.

```python
import plotille

canvas = plotille.Canvas(width=40, height=20)

# Draw rectangles
canvas.rect(0.1, 0.1, 0.4, 0.4, color='red')
canvas.rect(0.5, 0.5, 0.9, 0.9, color='blue')
canvas.rect(0.3, 0.3, 0.7, 0.7, color='green')

print(canvas.plot())
```

--------------------------------

### Plotille Color Functions

Source: https://context7.com/tammoippen/plotille/llms.txt

Demonstrates using plotille.color to wrap text with ANSI escape codes for terminal coloring. Supports named colors, 8-bit byte mode, and 24-bit RGB mode. Colors can be disabled using `no_color=True`.

```python
import plotille

# Named colors (3/4-bit mode)
print(plotille.color('Red text', fg='red'))
print(plotille.color('Blue background', bg='blue'))
print(plotille.color('Black on cyan', fg='black', bg='cyan'))

# Bright variants
print(plotille.color('Bright green', fg='bright_green'))

# 8-bit colors (256 color palette)
print(plotille.color('8-bit foreground', fg=196, mode='byte'))
print(plotille.color('8-bit both', fg=226, bg=17, mode='byte'))

# 24-bit RGB colors
print(plotille.color('RGB tuple', fg=(255, 128, 0), mode='rgb'))
print(plotille.color('RGB hex', fg='ff8000', bg='001122', mode='rgb'))

# Disable colors conditionally
print(plotille.color('No color', fg='red', no_color=True))

# Available named colors:
# black, red, green, yellow, blue, magenta, cyan, white
# bright_black, bright_red, bright_green, bright_yellow,
# bright_blue, bright_magenta, bright_cyan, bright_white
```

--------------------------------

### Add Text to Canvas

Source: https://context7.com/tammoippen/plotille/llms.txt

Places text strings at specific coordinates on the canvas.

```python
import plotille

canvas = plotille.Canvas(width=40, height=20)

# Add text at various positions
canvas.text(0.1, 0.9, 'Top Left', color='red')
canvas.text(0.6, 0.9, 'Top Right', color='blue')
canvas.text(0.1, 0.1, 'Bottom Left', color='green')
canvas.text(0.4, 0.5, 'Center', color='yellow')

print(canvas.plot())
```

--------------------------------

### Plot utility function

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Function for generating a quick plot from X and Y sequences.

```python
In [4]: plotille.plot?
Signature:
plotille.plot(
    X: Sequence[float | int] | Sequence[datetime.datetime],
    Y: Sequence[float | int] | Sequence[datetime.datetime],
    width: int = 80,
    height: int = 40,
    X_label: str = 'X',
    Y_label: str = 'Y',
    linesep: str = '\n',
    interp: Optional[Literal['linear']] = 'linear',
    x_min: float | int | datetime.datetime | None = None,
    x_max: float | int | datetime.datetime | None = None,
    y_min: float | int | datetime.datetime | None = None,
    y_max: float | int | datetime.datetime | None = None,
    lc: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    bg: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    color_mode: Literal['names', 'byte', 'rgb'] = 'names',
    origin: bool = True,
    marker: str | None = None,
) -> str
Docstring:
Create plot with X , Y values and linear interpolation between points

Parameters:
    X: List[float]         X values.
    Y: List[float]         Y values. X and Y must have the same number of entries.
    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.
    X_label: str           Label for X-axis.
    Y_label: str           Label for Y-axis. max 8 characters.    linesep: str           The requested line separator. default: os.linesep
    linesep: str           The requested line separator. default: os.linesep
    interp: Optional[str]  Specify interpolation; values None, 'linear'
    x_min, x_max: float    Limits for the displayed X values.
    y_min, y_max: float    Limits for the displayed Y values.
    lc: ColorDefinition           Give the line color.
    bg: ColorDefinition           Give the background color.
    color_mode: ColorMode        Specify color input mode; 'names' (default), 'byte' or
                           'rgb' see plotille.color.__docs__
    origin: bool           Whether to print the origin. default: True
    marker: str            Instead of braille dots set a marker char for actual
                           values.

Returns:
    str: plot over `X`, `Y`.
```

```python
In [5]: print(plotille.plot(X, np.sin(X), height=30, width=60))
```

--------------------------------

### Basic Scatter Plot with plotille.scatter

Source: https://context7.com/tammoippen/plotille/llms.txt

Generates a basic scatter plot displaying discrete data points without interpolation. Uses braille dots as default markers.

```python
import numpy as np
import plotille

# Generate random scatter data
np.random.seed(42)
x = np.random.normal(0, 1, 100)
y = np.random.normal(0, 1, 100)

# Basic scatter plot
print(plotille.scatter(x, y, height=20, width=60))
```

--------------------------------

### Basic Aggregated Histogram with plotille.hist_aggregated

Source: https://context7.com/tammoippen/plotille/llms.txt

Creates a histogram from pre-aggregated data, including counts and bin edges. Useful for integrating with data sources that provide summary statistics.

```python
import plotille

# Pre-aggregated histogram data (e.g., from monitoring APIs)
counts = [1945, 0, 0, 0, 0, 0, 10555, 798, 0, 28351, 0]
bins = [float('-inf'), 10, 50, 100, 200, 300, 500, 800, 1000, 2000, 10000, float('+inf')]

# Basic aggregated histogram
print(plotille.hist_aggregated(counts, bins))
```

--------------------------------

### Create Scatter Plot with Plotille

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Use plotille.scatter to create a scatter plot from X and Y coordinates. Customize width, height, and labels. Ensure X and Y have the same number of entries.

```python
print(plotille.scatter(X, np.sin(X), height=30, width=60))
```

--------------------------------

### Figure.clear

Source: https://context7.com/tammoippen/plotille/llms.txt

Clears all content from a Figure instance.

```APIDOC
## Figure.clear

### Description
Removes all plots, texts, spans, and images from the figure to allow reuse of the instance.

### Response
None
```

--------------------------------

### Figure Class Methods

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Methods available on the Figure class for creating various plot elements and managing the figure.

```APIDOC
## Figure Class Methods

### Description
Provides methods for creating scatter plots, histograms, text, lines, spans, and images on a figure.

### Methods
- `scatter(self, X, Y, lc=None, label=None, marker=None)`: Creates a scatter plot with no interpolation between points.
- `histogram(self, X, bins=160, lc=None)`: Creates a histogram over the provided X values.
- `text(self, X, Y, texts, lc=None)`: Prints text at specified coordinates.
- `axvline(self, x, ymin=0, ymax=1, lc=None)`: Plots a vertical line at a given x-coordinate.
- `axvspan(self, xmin, xmax, ymin=0, ymax=1, lc=None)`: Plots a vertical rectangle.
- `axhline(self, y, xmin=0, xmax=1, lc=None)`: Plots a horizontal line at a given y-coordinate.
- `axhspan(self, ymin, ymax, xmin=0, xmax=1, lc=None)`: Plots a horizontal rectangle.
- `imgshow(self, X, cmap=None)`: Displays data as an image on a 2D raster.
- `clear(self)`: Removes all plots, texts, spans, and images from the figure.
- `show(self, legend=False)`: Creates a canvas, plots registered elements, and returns the display string.
```

--------------------------------

### Create Aggregated Histogram with Plotille

Source: https://github.com/tammoippen/plotille/blob/master/README.md

Use `hist_aggregated` when you have pre-counted data for specific bins. Ensure the number of bins is one more than the number of counts.

```python
In [8]: plotille.hist_aggregated?
Signature:
plotille.hist_aggregated(
    counts: list[int],
    bins: Sequence[float],
    width: int = 80,
    log_scale: bool = False,
    linesep: str = '\n',
    lc: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    bg: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    color_mode: Literal['names', 'byte', 'rgb'] = 'names',
    meta: plotille._data_metadata.DataMetadata | None = None,
)
Docstring:
Create histogram for aggregated data.

Parameters:
    counts: List[int]         Counts for each bucket.
    bins: List[float]         Limits for the bins for the provided counts: limits for
                              bin `i` are `[bins[i], bins[i+1])`.
                              Hence, `len(bins) == len(counts) + 1`.
    width: int                The number of characters for the width (columns).
    log_scale: bool           Scale the histogram with `log` function.
    linesep: str              The requested line separator. default: os.linesep
    lc: ColorDefinition       Give the line color.
    bg: ColorDefinition       Give the background color.
    color_mode: ColorMode     Specify color input mode; 'names' (default), 'byte' or
                              'rgb' see plotille.color.__docs__
    meta: DataMetadata | None For conversion of datetime values.
Returns:
    str: histogram over `X` from left to right.

In [9]: counts = [1945, 0, 0, 0, 0, 0, 10555, 798, 0, 28351, 0]
In [10]: bins = [float('-inf'), 10, 50, 100, 200, 300, 500, 800, 1000, 2000, 10000, float('+inf')]
In [11]: print(plotille.hist_aggregated(counts, bins))
```

--------------------------------

### Scatter Plot with Custom Marker and Labels using plotille.scatter

Source: https://context7.com/tammoippen/plotille/llms.txt

Creates a scatter plot with custom axis labels and a specified marker character. Useful for highlighting specific data points.

```python
import numpy as np
import plotille

# Generate random scatter data
np.random.seed(42)
x = np.random.normal(0, 1, 100)
y = np.random.normal(0, 1, 100)

# Scatter plot with custom marker
print(plotille.scatter(
    x, y,
    height=20,
    width=60,
    X_label='X Values',
    Y_label='Y Values',
    lc='cyan',
    marker='*'             # Use asterisk as marker instead of braille dots
))
```