Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Tutorial

This is a basic introduction to using the library. Please refer to the API Reference for detailed description of the features and functionality provided by the library.

For this tutorial we’ll be using the image below:

The image has a resolution of 288x288 pixels.

Note

All the samples in this tutorial occurred in a terminal window of 255 columns by 70 lines.

## Creating an Instance

Image instances can be created using the convenience functions `AutoImage()`, `from_file()` and `from_url()`, which automatically detect the best style supported by the terminal emulator.

Instances can also be created using the Image Classes directly via their respective constructors or `from_file()` and `from_url()` methods.

1. Initialize with a file path:

       from term_image.image import from_file

       image = from_file("path/to/python.png")

2. Initialize with a URL:

       from term_image.image import from_url

       image = from_url("https://raw.githubusercontent.com/AnonymouX47/term-image/main/docs/source/resources/tutorial/python.png")

3. Initialize with a PIL (Pillow) image instance:

       from PIL import Image
       from term_image.image import AutoImage

       img = Image.open("path/to/python.png")
       image = AutoImage(img)

## Rendering an Image

Rendering an image is the process of converting it (per-frame for animated images) into text (a string) which reproduces a representation or approximation of the image when written to the terminal.

Hint

To display the rendered image in the following steps, pass the string as an argument to `print()`.

There are two ways to render an image:

### Unformatted Rendering

This is done using:

    str(image)

The image is rendered without padding/alignment and with transparency enabled.

The output (using `print()`) should look like:

### Formatted Rendering

Note

To see the effect of alignment in the steps below, set the image size smaller than your terminal size, with e.g:

    image.height = 50

This sets the image height to `50` lines (which is less than `70`, the height of the terminal window used to prepare this tutorial) and the width proportionally.

We’ll see more about this later.

Below are examples of formatted rendering:

    format(image, "|200.^70#ffffff")

Renders the image with:

- center horizontal alignment

- a padding width of 200 columns

- top vertical alignment

- a padding height of 70 lines

- white (`#ffffff`) background underlay

Note

You might have to reduce the padding width (200) and/or height (70) to something that’ll fit into your terminal window, or increase the size of the terminlal window

The output (using `print()`) should look like:

    f"{image:>._#.5}"

Renders the image with:

- right horizontal alignment

- default padding width (the current terminal width)

- bottom vertical alignment

- default padding height (the current terminal height minus two (`2`))

- transparent background with 0.5 alpha threshold

The output (using `print()`) should look like:

    "{:1.1#}".format(image)

Renders the image with:

- center horizontal alignment (default)

- no horizontal padding, since `1` is less than or equal to the image width

- middle vertical alignment (default)

- no vertical padding, since `1` is less than or equal to the image height

- transparency is disabled (alpha channel is ignored)

The output (using `print()`) should look like:

See also

Render Formatting and Render Format Specification

## Drawing/Displaying an Image

There are two basic ways to draw an image to the terminal screen:

1. Using the `draw()` method:

       image.draw()

   NOTE: `draw()` has various parameters for Render Formatting.

2. Using `print()` with an image render output (i.e printing the rendered string):

       print(image)  # Uses str()
       # OR
       print(f"{image:>200.^70#ffffff}")  # Uses format()

Note

- For animated images, only the former animates the output, the latter only draws the current frame (see `seek()` and `tell()`).

- Also, the former performs size validation to see if the image will fit into the terminal, while the latter doesn’t.

Important

All the examples above use dynamic and automatic sizing.

## Image Size

The size of an image determines the dimension of its render output.
The image size can be retrieved via the `size`, `width` and `height` properties.

The size of an image can be in either of two states:

1. Fixed

   In this state,

   - the `size` property evaluates to a 2-tuple of integers, while the `width` and `height` properties evaluate to integers,

   - the image is rendered with the set size.

2. Dynamic

   In this state,

   - the `size`, `width` and `height` properties evaluate to a `Size` enum member,

   - the size with which the image is rendered is automatically calculated (based on the current terminal size or the image’s original size) whenever the image is to be rendered.

The size of an image can be set at instantiation by passing an integer or a `Size` enum member to either the width or the height keyword-only parameter. For whichever axis a dimension is given, the dimension on the other axis is calculated proportionally.

Note

1. The arguments can only be given by keyword.

2. If neither is given, the `FIT` dynamic size applies.

3. All methods of instantiation accept these arguments.

For example:

    >>> from term_image.image import Size, from_file
    >>> image = from_file("python.png")  # Dynamic FIT
    >>> image.size is Size.FIT
    True
    >>> image = from_file("python.png", width=60)  # Fixed
    >>> image.size
    (60, 30)
    >>> image.height
    30
    >>> image = from_file("python.png", height=56)  # Fixed
    >>> image.size
    (112, 56)
    >>> image.width
    112
    >>> image = from_file("python.png", height=Size.FIT)  # Fixed FIT
    >>> image.size
    (136, 68)
    >>> image = from_file("python.png", width=Size.FIT_TO_WIDTH)  # Fixed FIT_TO_WIDTH
    >>> image.size
    (255, 128)
    >>> image = from_file("python.png", height=Size.ORIGINAL)  # Fixed ORIGINAL
    >>> image.size
    (288, 144)

No size validation is performed i.e the resulting size might not fit into the terminal window

    >>> image = from_file("python.png", height=68)  # Will fit in, OK
    >>> image.size
    (136, 68)
    >>> image = from_file("python.png", height=500)  # Will not fit in, also OK
    >>> image.size
    (1000, 500)

An exception is raised when both width and height are given.

    >>> image = from_file("python.png", width=100, height=100)
    Traceback (most recent call last):
      .
      .
      .
    ValueError: Cannot specify both width and height

The `width` and `height` properties can be used to set the size of an image after instantiation, resulting in fixed size.

    >>> image = from_file("python.png")
    >>> image.width = 56
    >>> image.size
    (56, 28)
    >>> image.height
    28
    >>> image.height = 68
    >>> image.size
    (136, 68)
    >>> image.width
    136
    >>> # Even though the terminal can't contain the resulting height, the size is still set
    >>> image.width = 200
    >>> image.size
    (200, 100)
    >>> image.width = Size.FIT
    >>> image.size
    (136, 69)
    >>> image.height = Size.FIT_TO_WIDTH
    >>> image.size
    (255, 128)
    >>> image.height = Size.ORIGINAL
    >>> image.size
    (288, 144)

The `size` property can only be set to a `Size` enum member, resulting in dynamic size.

    >>> image = from_file("python.png")
    >>> image.size = Size.FIT
    >>> image.size is image.width is image.height is Size.FIT
    True
    >>> image.size = Size.FIT_TO_WIDTH
    >>> image.size is image.width is image.height is Size.FIT_TO_WIDTH
    True
    >>> image.size = Size.ORIGINAL
    >>> image.size is image.width is image.height is Size.ORIGINAL
    True

Important

1. The currently set cell ratio is also taken into consideration when calculating sizes for images of Text-based Render Styles.

2. There is a 2-line difference between the default frame size and the terminal size to allow for shell prompts and the likes.

Tip

See `set_size()` for extended sizing control.

To explore more of the library’s features and functionality, check out the User Guide and the API Reference.