Docs: Placement and control sequence examples

docs/usage/examples/emitting_control_sequences.rst

@@ -0,0 +1,82 @@
+.. _sequence example:
+
+================================
+Animating with control sequences
+================================
+
+.. py:currentmodule:: chafa
+
+This is a fun little example that demonstrates how to use the :py:meth:`TermInfo.emit` method.
+
+.. image:: example_img/animation.gif
+    :width: 300
+    :align: center
+
+The code that produced this animation follows:
+
+::
+
+    from chafa import *
+    from time import sleep
+    import sys
+
+    SL=15
+
+    def snake(n, step):
+        if step < 0: turns = ["┏","┛"]
+        else:        turns = ["┓", "┗"]
+
+        if n == 1:
+            return turns[0]
+        elif n == SL - 1:
+            return turns[1]
+
+        return "┃"
+
+    def gradient(x, y):
+        return (80 + 5*x, 255 - (100 + 10*y), 200)
+
+    # Grab our info
+    db = TermDb()
+    info = db.detect()
+
+    # Clear the terminal
+    clear     = info.emit(TermSeq.CHAFA_TERM_SEQ_CLEAR)
+    no_cursor = info.emit(TermSeq.CHAFA_TERM_SEQ_DISABLE_CURSOR)
+
+    print(clear.decode())
+    print(no_cursor.decode())
+
+    rows = list(range(1,SL))
+    cols = list(range(1,32))
+
+    for x in cols:
+        # We want to step backwards if column is even
+        step = 2 * (x%2) - 1
+
+        for y in rows[::step]:
+            # Grab char
+            char = snake(y, step)
+
+            # Move to position
+            out = info.emit(
+                TermSeq.CHAFA_TERM_SEQ_CURSOR_TO_POS, 
+                x, y
+            )
+
+            # Set color
+            color = info.emit(
+                TermSeq.CHAFA_TERM_SEQ_SET_COLOR_FG_DIRECT,
+                *gradient(x,y)
+            )
+
+            sys.stdout.buffer.write(out)
+            sys.stdout.buffer.write(color)
+            sys.stdout.write(char)
+            sys.stdout.flush()
+
+            sleep(0.01)
+
+    # All back to normal!
+    reset = info.emit(TermSeq.CHAFA_TERM_SEQ_RESET_TERMINAL_HARD)
+    print(reset.decode())

docs/usage/examples/examples.rst

@@ -10,21 +10,26 @@ If you are the sort of person who likes getting their hands dirty right away, ta
 
 All the examples will be using this image and calling it ``snake.jpg``
 
+Some more examples might be found in the `examples folder <https://github.com/GuardKenzie/chafa.py/tree/main/examples>`_ on GitHub.
+
 .. image:: ../snake.jpg
     :width: 300
     :align: center
 
 
 .. toctree::
    :maxdepth: 2
-   :caption: Here's all the examples we got
+   :caption: Here's all the examples on the webpage.
 
    reading_an_image
    aspect_ratio
    detecting_capabilities
    raw_color
-   emitting_sequences
+   emitting_control_sequences
    converting_to_html
+   using_placement
+
+
 
 
 

docs/usage/examples/using_placement.rst

@@ -0,0 +1,72 @@
+.. py:currentmodule:: chafa
+===========================
+Using :py:class:`Placement`
+===========================
+
+Here is an example on how to use the :py:class:`Placement` class to draw an image in the center of the :py:class:`Canvas`.
+
+.. image:: example_img/center_snake.png
+    :width: 500
+    :align: center
+
+.. versionadded:: 1.2.0
+
+::
+
+    import chafa
+    from pathlib import Path
+    from PIL import Image
+
+    # Init canvas config
+    config = chafa.CanvasConfig()
+
+    # Set canvas height and width
+    config.width = 70
+    config.height = 20
+
+    # Set cell dimensions for accurate aspect ratio
+    config.cell_width  = 18
+    config.cell_height = 46
+
+    # Set pixel mode
+    config.pixel_mode = chafa.PixelMode.CHAFA_PIXEL_MODE_KITTY
+
+    # Open image with PIL
+    image = Image.open(Path(__file__).parent / "snake.jpg")
+
+    width  = image.width
+    height = image.height
+    bands  = len(image.getbands())
+
+    # Put image into correct format
+    pixels = image.tobytes()
+
+    # Init the canvas
+    canvas = chafa.Canvas(config)
+
+    # Init frame
+    frame = chafa.Frame(
+        chafa.PixelType.CHAFA_PIXEL_RGB8,
+        pixels,
+        height,
+        width,
+        width * bands
+    )
+
+    # Init image and assign our frame to it
+    chafa_image = chafa.Image()
+    chafa_image.frame = frame
+
+    # Init the placement of our image
+    placement = chafa.Placement(chafa_image)
+
+    # Set our desired placement
+    placement.tuck   = chafa.Tuck.CHAFA_TUCK_SHRINK_TO_FIT
+    placement.halign = chafa.Align.CHAFA_ALIGN_CENTER
+    placement.valign = chafa.Align.CHAFA_ALIGN_CENTER
+
+    # Put the image on the canvas
+    canvas.placement = placement
+
+    # Write picture
+    print(canvas.print().decode())

examples/example_placement.py

@@ -6,7 +6,7 @@
 config = chafa.CanvasConfig()
 
 # Set canvas height and width
-config.width = 120
+config.width = 70
 config.height = 20
 
 # Set cell dimensions for accurate aspect ratio
@@ -23,12 +23,6 @@
 height = image.height
 bands  = len(image.getbands())
 
-config.calc_canvas_geometry(
-    width,
-    height,
-    11/24
-)
-
 # Put image into correct format
 pixels = image.tobytes()