### Install PicTex in a Virtual Environment

Source: https://github.com/francozanardi/pictex/blob/main/README.md

Recommended method for installing PicTex to avoid permission issues and ensure a clean setup. Uninstall existing versions first, then create and activate a virtual environment before installing.

```bash
pip uninstall pictex skia-python

python -m venv .venv
.\.venv\Scripts\activate

pip install pictex
```

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

### Install PicTex

Source: https://context7.com/francozanardi/pictex/llms.txt

Install PicTex using pip within a virtual environment.

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install pictex
```

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

### Install PicTex in a Virtual Environment

Source: https://github.com/francozanardi/pictex/blob/main/README.md

It is highly recommended to install PicTex in a virtual environment to avoid conflicts. This includes creating and activating the environment, then installing the package.

```bash
python -m venv .venv

# On Windows:
.\.venv\Scripts\activate

# On macOS/Linux:
# source .venv/bin/activate

pip install pictex
```

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

### Force Reinstall PicTex with Administrator Privileges

Source: https://github.com/francozanardi/pictex/blob/main/README.md

Alternative installation method for users unable to use virtual environments. Requires running the command in a terminal with administrator rights to ensure proper installation of dependencies.

```bash
pip install --force-reinstall pictex
```

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

### Canvas Setup and Rendering

Source: https://context7.com/francozanardi/pictex/llms.txt

Configure a Canvas with global styles and render text to an image file. Supports various rendering options like scale factor and crop mode.

```python
from pictex import Canvas, Shadow, LinearGradient, CropMode

canvas = (
    Canvas()
    .font_family("Poppins-Bold.ttf")   # path to a .ttf/.otf file, or a system font name
    .font_size(60)
    .color("white")
    .padding(20)
    .background_color(LinearGradient(["#2C3E50", "#FD746C"]))
    .border_radius(10)
    .text_shadows(Shadow(offset=(2, 2), blur_radius=3, color="black"))
)

# Render a plain string — returns BitmapImage
image = canvas.render("Hello, World! 🎨✨")
image.save("hello.png")

# Render with scale factor for high-DPI output
hires = canvas.render("Hello!", scale_factor=2.0)
hires.save("hello_2x.png")

# Render with crop mode
smart = canvas.render("Hello!", crop_mode=CropMode.SMART)
smart.save("hello_smart.png")

# Render as SVG — returns VectorImage
svg = canvas.render_as_svg("Hello, SVG!", embed_font=True)
svg.save("hello.svg")
```

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

### Build and Style an Avatar Image

Source: https://context7.com/francozanardi/pictex/llms.txt

Use the Image builder to load and style raster images. This example demonstrates setting size, circular crop with border-radius, borders, and box shadows.

```python
from pictex import Canvas, Image, Shadow

avatar = (
    Image("profile.jpg")
    .size(100, 100)
    .border_radius("50%")       # circular crop
    .border(3, "white")
    .box_shadows(Shadow(offset=(2, 2), blur_radius=8, color="#00000055"))
)

# Resize proportionally
thumbnail = Image("photo.jpg").resize(0.5)  # 50% of original

# Use as a background with cover mode (Image is also usable as a standalone builder)
from pictex import Row
hero = (
    Row()
    .size(800, 400)
    .background_image("hero.jpg", "cover")
)

Canvas().render(avatar).save("avatar.png")
```

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

### Create a User Profile Banner with Row and Column

Source: https://context7.com/francozanardi/pictex/llms.txt

Use Row to place elements horizontally and Column to stack them vertically. This example demonstrates aligning items and justifying content within a Row.

```python
from pictex import Canvas, Row, Image, Text, Column

avatar = Image("avatar.jpg").size(60, 60).border_radius("50%")
user_info = Column(
    Text("Alex Doe").font_size(20).font_weight(700),
    Text("@alexdoe").font_size(14).color("#657786")
).gap(4)

banner = (
    Row(avatar, user_info)
    .gap(15)
    .align_items("center")          # vertical alignment: start | center | end | stretch
    .justify_content("space-between") # horizontal distribution
    .size(width=500)
    .padding(20)
    .background_color("#F5F8FA")
)

Canvas().render(banner).save("banner.png")
```

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

### Convert Image to Pillow Image

Source: https://context7.com/francozanardi/pictex/llms.txt

Converts the image to a Pillow Image object. Requires Pillow to be installed.

```python
pil_img = image.to_pillow()
pil_img.show()
```

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

### Get Image Dimensions

Source: https://context7.com/francozanardi/pictex/llms.txt

Prints the width and height of the image.

```python
print(image.width, image.height)
```

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

### Save and Convert BitmapImage

Source: https://github.com/francozanardi/pictex/blob/main/docs/getting_started.md

Use the BitmapImage object to save the rendered image to a file, convert it to a Pillow Image object for display, or get it as a NumPy array.

```python
# Assuming 'image' is an Image object from the example above

# Save to a file (format is inferred from extension)
image.save("output.png")

# Get a Pillow Image object (requires `pip install Pillow`)
pil_image = image.to_pillow()
pil_image.show()

# Get a NumPy array for use with other libraries
numpy_array_bgra = image.to_numpy()
```

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

### Render Text with Ligatures and Special Characters

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Enable automatic text shaping for features like ligatures, which replace character sequences with single glyphs. This example uses FiraCode font to demonstrate ligature rendering.

```python
from pictex import Canvas, NamedColor

(
    Canvas()
    .font_family("FiraCode-Medium.ttf")
    .font_size(100)
    .background_color(NamedColor.BEIGE)
    .color(NamedColor.BLUE)
    .render("-> != <= ==")
    .save("ligature.png")
)
```

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

### Get Raw Image Bytes

Source: https://context7.com/francozanardi/pictex/llms.txt

Retrieves the raw image data as bytes in BGRA 32-bit format.

```python
raw = image.to_bytes()
```

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

### Build and Run PicTex Tests Locally

Source: https://github.com/francozanardi/pictex/blob/main/README.md

Builds a Docker image for testing and runs the tests within a container, matching the CI environment. Mounts the current directory into the container for access to the codebase.

```bash
docker build -f Dockerfile.test -t pictex-test .
docker run --rm -v "$(pwd):/app" pictex-test pytest
```

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

### Basic PicTex Composition with Builders

Source: https://github.com/francozanardi/pictex/blob/main/docs/core_concepts.md

Demonstrates the creation of a nested composition using Row, Column, and Text builders, then rendering it to an image.

```python
from pictex import *

composition = Row(
    Column(
        Text("Col1").background_color("blue"),
        Text("Col1").background_color("red")
    ),
    Column(
        Text("Col2").background_color("blue"),
        Text("Col2").background_color("red")
    )
)
Canvas().render(composition).save("introduction.png")
```

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

### Create a User Banner with PicTex

Source: https://github.com/francozanardi/pictex/blob/main/docs/getting_started.md

Compose Image and Text builders within Row and Column layouts, then render to a Canvas and save as a PNG. This demonstrates the core composition workflow.

```python
from pictex import Canvas, Row, Column, Text, Image

# 1. Create the individual content builders
avatar = (
    Image("avatar.jpg")
    .size(60, 60)
    .border_radius('50%') # Make it circular
)

user_info = Column(
    Text("Alex Doe").font_size(20).font_weight(700),
    Text("@alexdoe").color("#657786")
).gap(4) # Add a 4px vertical gap between the texts

# 2. Compose the builders in a layout container
user_banner = Row(
    avatar,
    user_info
).gap(15).align_items('center')  # Vertically center the avatar and user info

# 3. Create a Canvas and render the final composition
canvas = Canvas().padding(20).background_color("#F5F8FA")
image = canvas.render(user_banner)

# 4. Save the result
image.save("user_banner.png")
```

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

### Generating Bitmap Images with PicTex

Source: https://context7.com/francozanardi/pictex/llms.txt

Shows how to use `Canvas.render()` to produce a `BitmapImage` object, which can then be saved to a file.

```python
from pictex import Canvas

image = Canvas().font_size(80).color("navy").render("Hello")


```

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

### Apply Solid Colors and Gradients

Source: https://context7.com/francozanardi/pictex/llms.txt

Demonstrates various ways to apply solid colors (named, hex, RGB) and different types of gradients (linear, radial, sweep, conical) to text, backgrounds, strokes, underlines, and borders.

```python
from pictex import (
    Canvas, SolidColor, NamedColor,
    LinearGradient, RadialGradient, SweepGradient, TwoPointConicalGradient
)

# Solid colors — all equivalent for red:
Canvas().color("red")
Canvas().color("#FF0000")
Canvas().color("#F00")
Canvas().color(NamedColor.RED)
Canvas().color(SolidColor(255, 0, 0, 255))

# Linear gradient on background
bg = LinearGradient(
    colors=["#43C6AC", "#191654"],
    start_point=(0.0, 0.0),  # top-left
    end_point=(1.0, 1.0)     # bottom-right
)

# Radial, sweep and two-point conical
radial = RadialGradient(["yellow", "orange", "purple"])
sweep  = SweepGradient(["red", "yellow", "lime", "cyan", "blue", "red"])
conical = TwoPointConicalGradient(colors=["yellow", "blue"], start=(0.5, 0))

canvas = (
    Canvas()
    .font_family("Impact")
    .font_size(150)
    .color(LinearGradient(["#FFD700", "#FF6B6B"]))          # gradient text
    .background_color(sweep)                                  # gradient background
    .text_stroke(width=8, color=RadialGradient(["#4A00E0", "#8E2DE2"]))  # gradient stroke
    .underline(thickness=15, color=LinearGradient(["#00F260", "#0575E6"]))
    .border(10, LinearGradient(["blue", "darkcyan"]))
    .padding(30)
)
canvas.render("GRADIENTS!").save("gradients_everywhere.png")
```

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

### Styling Text with PicTex

Source: https://context7.com/francozanardi/pictex/llms.txt

Demonstrates fluent methods for setting font properties, colors, spacing, alignment, and text decorations. Supports variable fonts and text shadows.

```python
from pictex import Canvas, Text, Shadow, FontWeight, FontStyle

canvas = (
    Canvas()
    .font_family("Oswald-VariableFont_wght.ttf")  # variable font
    .font_size(80)
    .font_weight(FontWeight.BLACK)   # 100–900 or enum: THIN, LIGHT, REGULAR, BOLD, BLACK…
    .font_style(FontStyle.ITALIC)
    .color("#00FFAA")
    .letter_spacing(4)               # px offset; "10%" of space-char; "normal" to reset
    .line_height(1.4)                # multiplier; "auto" for font-native metrics
    .text_align("center")            # left | center | right
    .text_box_edge("glyphs")         # "font" (default) | "glyphs" for tight ink bounds
    .text_shadows(
        Shadow(offset=(0, 0), blur_radius=2, color="#00FFAA"),
        Shadow(offset=(0, 0), blur_radius=8, color="#FFFFFF"),
    )
    .text_stroke(width=5, color="black", mode="outline")  # center | outline | inline
    .underline(thickness=4, color="white")
    .strikethrough(thickness=3, color="red")
)

canvas.render("NEON TYPE").save("typography.png")

# Fallback fonts for multilingual / emoji content
multilingual = (
    Canvas()
    .font_family("Lato-BoldItalic.ttf")
    .font_fallbacks("NotoSansJP-Regular.ttf")  # auto-used when primary lacks a glyph
    .font_size(60)
    .render("Hello, 世界 ✨ 👩‍🔬")
)
multilingual.save("multilingual.png")
```

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

### Text Direction and BiDi Handling in PicTex

Source: https://context7.com/francozanardi/pictex/llms.txt

Explains automatic Unicode Bidirectional Algorithm processing and how to set explicit text direction using `.direction()`. Demonstrates RTL mirroring of child order in Rows.

```python
from pictex import Canvas, Column, Row, Text

# Automatic BiDi — no configuration needed for mixed-direction text
Canvas().padding(20).background_color("lightgray").render("Hello مرحبا World").save("bidi_auto.png")

# Explicit RTL: Row children are mirrored, text right-aligns by default
rtl_layout = (
    Column(
        Row(
            Text("A").background_color("red").padding(5),
            Text("B").background_color("orange").padding(5),
        ).gap(10),                         # renders as [B][A] in RTL
        Text("Right-aligned").size(width=400),
        Text("LTR Override").direction("ltr"),
    )
    .direction("rtl")
    .padding(20).gap(20).background_color("lightgray")
)
Canvas().render(rtl_layout).save("rtl.png")
```

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

### Render and Save Raster Images

Source: https://github.com/francozanardi/pictex/blob/main/docs/exporting.md

Use the `.render()` method to create a BitmapImage object and then save it to a file. The file format is inferred from the extension. You can also specify quality for JPG output.

```python
from pictex import Canvas

canvas = Canvas().font_size(80).color("blue")
image = canvas.render("Hello, World!")

# Save to a file (format is inferred from extension)
image.save("output.png")
image.save("output.jpg", quality=90)
```

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

### Apply Box Model Properties

Source: https://context7.com/francozanardi/pictex/llms.txt

Demonstrates CSS box-model properties like size, padding, margin, border, and shadow. It also covers size constraints such as min/max width/height and aspect ratio.

```python
from pictex import Canvas, Row, Column, Text, Shadow

box = (
    Row(Text("Content"))
    .size(width=300, height=150)   # total outer box, border-box model
    .padding(20)                    # inner spacing; narrows content area
    .padding_top(10)                # per-side helpers available
    .margin(10)                     # outer spacing
    .border(5, "#333", "dashed")    # solid | dashed | dotted
    .border_radius(12)              # pixels; "50%" for circle
    .background_color("white")
    .box_shadows(Shadow(offset=(4, 4), blur_radius=8, color="#00000040"))
    .overflow("hidden")             # clip children to padding box
)

# Size constraints
responsive = (
    Column(Text("Dynamic content"))
    .size(width="50%")
    .min_width(300)
    .max_width(800)
    .min_height(100)
    .aspect_ratio(16/9)
)

Canvas().render(box).save("box_model.png")
```

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

### Element Sizing with Border-Box Model

Source: https://github.com/francozanardi/pictex/blob/main/docs/box_model.md

Demonstrates the border-box sizing model where padding and border are included within the element's defined size. The content area is reduced accordingly.

```python
# This element's final width in the layout is exactly 300px.
box = Row(Text("Content"))\
    .size(width=300)\
    .padding(20)\
    .border(5, "blue")

# The content area inside is now 300 - (2*20 padding) - (2*5 border) = 250px wide.
```

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

### Set Minimum and Maximum Size Constraints

Source: https://github.com/francozanardi/pictex/blob/main/docs/box_model.md

Defines minimum and maximum dimensions for elements to control their responsiveness. Supports pixel and percentage values.

```python
from pictex import *

# Prevent collapse with minimum size
card = Column(
    Text("Dynamic content")
).min_width(200).min_height(100)

# Prevent overflow with maximum size
description = Text(long_text).max_width(400).max_height(200)

# Combine constraints for responsive layouts
flexible_box = Row(children).size(width="50%").min_width(300).max_width(800)
```

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

### Flex Layout Control in PicTex

Source: https://context7.com/francozanardi/pictex/llms.txt

Illustrates how to control flexbox properties like grow, shrink, and wrap for container children. Demonstrates self-alignment and gap between items.

```python
from pictex import Canvas, Row, Column, Text

# flex_grow / flex_shrink
row = Row(
    Text("Fixed").size(width=100),
    Text("Grows x1").flex_grow(1).background_color("lightblue"),
    Text("Grows x2").flex_grow(2).background_color("lightgreen"),
).size(width=600)

# align_self overrides container alignment for one item
mixed = Row(
    Text("Top").align_self("start"),
    Text("Middle").align_self("center"),
    Text("Bottom").align_self("end"),
).size(height=100).background_color("lightyellow")

# flex_wrap creates multi-line grid layouts
grid = (
    Row(*[Text(f"Item {i}").size(width=100).padding(8).background_color("lavender") for i in range(15)])
    .flex_wrap("wrap")
    .gap(8)
    .size(width=400)
)

Canvas().font_size(20).render(Column(row, mixed, grid).gap(20)).save("flex_layout.png")
```

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

### Set Font Properties with System or Local Fonts

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Configure font family, size, weight, and style using system-installed fonts or local font files. Ensure the font file path is correct for local fonts.

```python
from pictex import Canvas, FontWeight, FontStyle

# Using a system font
canvas_system = (
    Canvas()
    .font_family("Georgia")
    .font_size(80)
    .font_weight(FontWeight.BOLD)
    .font_style(FontStyle.ITALIC)
)

# Using a local font file
canvas_local = Canvas().font_family("assets/fonts/Inter-Variable.ttf").font_size(80)
```

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

### Main Axis Distribution with justify-content

Source: https://github.com/francozanardi/pictex/blob/main/docs/core_concepts.md

Illustrates various justify-content values for distributing items along the main axis within a Row.

```python
from pictex import *

def create_distribution_example(distribution):
    row_with_distribution = Row(
        Text("A").background_color("blue"),
        Text("B").background_color("red"),
        Text("C").background_color("green"),
    ).justify_content(distribution).border(4, "black").size(width=300)
    return Column(
        Text(distribution).font_size(40),
        row_with_distribution
    ).background_color("pink")

distributions = [
    "start",
    "center",
    "end",
    "space-between",
    "space-around",
    "space-evenly",
]
examples = []
for d in distributions:
    examples.append(create_distribution_example(d))


image = Canvas().font_size(80).render(Column(*examples).gap(20))
image.save("distribution.png")
```

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

### Anchor-Based Positioning with .place()

Source: https://github.com/francozanardi/pictex/blob/main/docs/core_concepts.md

Use `.place()` to position elements using keywords, pixels, percentages, or offsets relative to the canvas viewport. This method is a shortcut for `fixed_position()` combined with `translate()`.

```python
from pictex import Canvas, Row, Text

background = Row().size(width=300, height=200).background_color("lightblue")
badge = Text("SALE").background_color("red").color("white").padding(5)

result = Canvas().render(
    background,
    badge.place("right", "top", x_offset=-10, y_offset=10)
)
result.save("badge_example.png")
```

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

### Automatic BiDi and RTL Text Direction

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Demonstrates automatic bidirectional text handling for Arabic and explicit right-to-left (RTL) text direction for layout control. Use when dealing with languages that require specific text flow.

```python
Canvas().background_color("lightgray").padding(20).render("Hello مرحبا World").save("auto_bidi.png")
```

```python
container = (
    Column(
        # This Row will be mirrored: [B] [A]
        Row(
            Text("A").background_color("red").padding(5),
            Text("B").background_color("orange").padding(5),
        ).gap(10),

        # This text will be right-aligned automatically
        Text("Right-aligned text").size(width=400), 
        
        # Explicit override to LTR
        Text("LTR Override").direction("ltr"), 
    )
    .direction("rtl")
    .padding(20)
    .gap(20)
    .background_color("lightgray")
)

Canvas().render(container).save("direction_example.png")
```

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

### Multi-line Text with Custom Alignment and Spacing

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Shows how to render multi-line text with custom alignment, line height, and padding using PicTex. Imports Canvas and TextAlign.

```python
from pictex import Canvas, TextAlign

canvas = (
    Canvas()
    .font_family("Times New Roman")
    .font_weight(700)
    .font_size(50)
    .color("magenta")
    .text_align(TextAlign.CENTER)  # a string is also accepted ("center")
    .line_height(1.2)
    .padding(20)
)

text = "This is an example of centered,\nmulti-line text\nwith custom line spacing."
canvas.render(text).save("alignment_example.png")
```

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

### Positioning Elements with PicTex

Source: https://context7.com/francozanardi/pictex/llms.txt

Shows how to position elements using anchor-based canvas-relative positioning, fixed positioning, absolute positioning, and relative offsets. Includes true centering with translate.

```python
from pictex import Canvas, Row, Column, Text, Image

# .place() — anchor-based canvas-relative positioning (most ergonomic)
background = Row().size(width=500, height=300).background_image("bg.jpg", "cover")
watermark   = Text("© 2025").font_size(16).color("white").place("right", "bottom", x_offset=-10, y_offset=-10)
overlay     = Text("SALE").background_color("red").color("white").padding(8).place("center", "top", y_offset=20)

# .fixed_position() — CSS position:fixed (relative to canvas viewport)
header = Text("Header").fixed_position(top=0, left=0, right=0)

# .absolute_position() — CSS position:absolute (relative to nearest ancestor)
badge = (
    Text("NEW")
    .font_size(12).color("white").background_color("red").padding(4, 8).border_radius(10)
    .absolute_position(top=-8, right=-12)
)

# .relative_position() — stays in flow, visually offset
nudged = Text("Slightly down").relative_position(top=5)

# .translate() — post-layout transform for true centering
centered = Text("Centered").fixed_position(top="50%", left="50%").translate(x="-50%", y="-50%")

Canvas().render(background, watermark, overlay, centered).save("positioning.png")
```

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

### Text Decorations (Underline and Strikethrough)

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Adds underline and strikethrough decorations to text. Decorations can be styled with colors or gradients, and will use the font color if not specified. Import Canvas.

```python
from pictex import Canvas

# Simple underline
canvas1 = Canvas().font_size(80).color("blue").underline(10)
canvas1.render("Underlined").save("underline.png")

# Styled strikethrough
canvas2 = Canvas().font_size(80).color("blue").strikethrough(thickness=10, color="red")
canvas2.render("Strikethrough").save("strikethrough.png")
```

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

### Generate Styled Text Image with PicTex

Source: https://github.com/francozanardi/pictex/blob/main/README.md

Create a stylized text image by defining a style template using PicTex's fluent API and then rendering text with it. The image can be saved to a file.

```python
from pictex import Canvas, Shadow, LinearGradient

# 1. Create a style template using the fluent API
canvas = (
    Canvas()
    .font_family("Poppins-Bold.ttf")
    .font_size(60)
    .color("white")
    .padding(20)
    .background_color(LinearGradient(["#2C3E50", "#FD746C"]))
    .border_radius(10)
    .text_shadows(Shadow(offset=(2, 2), blur_radius=3, color="black"))
)

# 2. Render some text using the template
image = canvas.render("Hello, World! 🎨✨")

# 3. Save or show the result
image.save("hello.png")
```

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

### Compose Complex Visuals with PicTex Components

Source: https://github.com/francozanardi/pictex/blob/main/README.md

Build complex visuals by composing elements like `Image`, `Column`, and `Text` using PicTex. The fluent API allows for declarative styling. The final image is rendered and saved.

```python
from pictex import *

# 1. Build your visual components
avatar = (
    Image("avatar.png")
    .border_radius("50%")
    .background_color("silver")
    .border(3, "white")
    .box_shadows(Shadow(offset=(2, 2), blur_radius=5, color="black"))
)

user_info = Column(
    Text("Alex Doe").font_size(24).font_weight(700).color("#184e77"),
    Text("Graphic Designer").color("#edf6f9").text_shadows(Shadow(offset=(1, 1), blur_radius=1, color="black")),
).align_items("center").gap(4)

# 2. Compose them in a layout container
card = (
    Column(avatar, user_info)
    .background_color(LinearGradient(["#d9ed92", "#52b69a"]))
    .border_radius(20)
    .padding(30)
    .align_items("center")
    .gap(20)
)

# 3. Render and save the final image
canvas = Canvas().font_family("NataSans.ttf")
image = canvas.render(card)
image.save("profile_card.png")
```

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

### Migrate layout distribution and alignment from v1.x to v2.0

Source: https://github.com/francozanardi/pictex/blob/main/docs/MIGRATION.md

Container layout methods like `horizontal_distribution`, `vertical_distribution`, `vertical_align`, and `horizontal_align` have been renamed to `justify_content` and `align_items` to match CSS Flexbox terminology.

```python
Row(children).horizontal_distribution("center").vertical_align("center")
Column(children).vertical_distribution("space-between").horizontal_align("stretch")
```

```python
Row(children).justify_content("center").align_items("center")
Column(children).justify_content("space-between").align_items("stretch")
```

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

### Create a Card Layout with Column

Source: https://context7.com/francozanardi/pictex/llms.txt

Utilize Column to stack text elements vertically for a card-like structure. This snippet shows setting font sizes, colors, gaps, padding, and background.

```python
from pictex import Canvas, Column, Text, Shadow

card = (
    Column(
        Text("Title").font_size(28).font_weight(700),
        Text("Subtitle").font_size(16).color("#666"),
        Text("Body text with more details about the topic.")
             .font_size(14).line_height(1.5).color("#333"),
    )
    .gap(10)
    .padding(24)
    .size(width=400)
    .background_color("white")
    .border_radius(12)
    .box_shadows(Shadow(offset=(0, 4), blur_radius=12, color="#00000033"))
)

Canvas().render(card).save("card.png")
```

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

### Text Styling and Alignment

Source: https://context7.com/francozanardi/pictex/llms.txt

Create and style Text elements, including multi-line wrapping, alignment, and inline Spans with different styles.

```python
from pictex import Canvas, Text, Span, TextAlign, LinearGradient

canvas = Canvas().font_family("Arial").font_size(50)

# Plain text with styling
t1 = (
    Text("Hello, World!")
    .font_size(60)
    .font_weight(700)
    .color("#184e77")
    .text_align(TextAlign.CENTER)
    .line_height(1.4)
    .underline(thickness=3, color="blue")
)

# Multi-line with wrapping inside a fixed-width container
t2 = (
    Text("This long sentence wraps automatically inside a 400px container.")
    .text_wrap("normal")   # "nowrap" to disable
)

# Inline spans with mixed styles
gradient = LinearGradient(colors=["purple", "orange"])
t3 = Text(
    "This is ",
    Span(
        "very ",
        Span("rich").font_weight("bold").color(gradient),
        " text!"
    ).color("blue").underline(thickness=4)
)

canvas.render(t1, t2, t3).save("text_examples.png")
```

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

### Utilize Variable Fonts with Weight and Style Axes

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Apply settings like `FontWeight.BLACK` to control the 'wght' axis of variable font files for dynamic styling. Ensure the font file is a variable font format.

```python
from pictex import Canvas, FontWeight, FontStyle

# Using a variable font file and setting its axes
canvas = (
    Canvas()
    .font_family("Oswald-VariableFont_wght.ttf")
    .font_size(80)
    .font_weight(FontWeight.BLACK) # Sets 'wght' axis to 900
    .color("orange")
)

canvas.render("Variable Font").save("variable_font.png")
```

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

### Using NamedColor Enum for Solid Colors

Source: https://github.com/francozanardi/pictex/blob/main/docs/colors.md

Demonstrates using the NamedColor enum for type-safe and autocompleted color selection. Ensure NamedColor is imported.

```python
from pictex import Canvas, SolidColor, NamedColor

Canvas().color(NamedColor.RED)
Canvas().color(NamedColor.CORNFLOWERBLUE)
Canvas().color(NamedColor.GOLD)
```

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

### Render Complex Emoji Sequences

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Demonstrates rendering multi-part emoji sequences as single glyphs using Canvas. Requires importing Canvas from pictex.

```python
from pictex import Canvas

( 
    Canvas()
    .font_size(100)
    .render("👩‍🔬 🏳️‍🌈")
    .save("docs-emoji.png")
)
```

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

### Save Image to File

Source: https://context7.com/francozanardi/pictex/llms.txt

Infers the output format from the file extension. Quality can be specified for JPEG and WebP.

```python
image.save("output.png")
image.save("output.jpg", quality=85)
image.save("output.webp", quality=90)
```

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

### Render and Save SVG Vector Images

Source: https://github.com/francozanardi/pictex/blob/main/docs/exporting.md

Use the `.render_as_svg()` method to generate a `VectorImage` object and save it as an SVG file. Note that shadows are not yet supported in SVG output.

```python
vector_image = canvas.render_as_svg("Hello, SVG!")
vector_image.save("output.svg")
```

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

### Migrate 'fill-available' size mode to flex_grow() in v2.0

Source: https://github.com/francozanardi/pictex/blob/main/docs/MIGRATION.md

The `'fill-available'` size mode has been removed. Use `flex_grow(1)` instead to explicitly define flex behavior, aligning with CSS standards.

```python
Text("Flexible").size(width='fill-available')
Row(children).size(height='fill-available')
```

```python
Text("Flexible").flex_grow(1)
Row(children).flex_grow(1)
```

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

### CropMode

Source: https://github.com/francozanardi/pictex/blob/main/docs/api/models.md

Enumeration for crop mode options.

```APIDOC
## enum pictex.CropMode

### Description
Enumeration for crop mode options.

### Parameters
(No specific parameters documented in the source for direct user invocation.)

### Request Example
(No request example provided in the source.)

### Response
(No response details provided in the source.)
```

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

### Inspect Render Tree

Source: https://context7.com/francozanardi/pictex/llms.txt

Iterates through the children of the image's render tree node to print their type and bounds.

```python
node = image.render_tree
for child in node.children:
    print(child.node_type, child.bounds)
```

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

### Control Raster Image Size with Crop Modes

Source: https://github.com/francozanardi/pictex/blob/main/docs/exporting.md

The `crop_mode` argument in `.render()` controls the final image dimensions. Options include `NONE` (default), `CONTENT_BOX` (crops to root element's content box), and `SMART` (trims transparent pixels). Save as JPG to easily visualize differences due to the black background.

```python
from pictex import Canvas, CropMode

canvas = Canvas().font_size(100).add_shadow(offset=(10,10), blur_radius=20, color="white")
canvas.background_color("blue")

# Render with different exporting modes
img_none = canvas.render("Test", crop_mode=CropMode.NONE)
img_smart = canvas.render("Test", crop_mode=CropMode.SMART)
img_content_box = canvas.render("Test", crop_mode=CropMode.CONTENT_BOX)

# We save them as JPG images to force a black background instead of transparent, so it's easier to see the difference
img_none.save("test_none.jpg")
img_smart.save("test_smart.jpg")
img_content_box.save("test_content_box.jpg")
```

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

### Canvas Builder and Renderer

Source: https://context7.com/francozanardi/pictex/llms.txt

The Canvas is the top-level container for building images. It sets global styles and acts as the entry point for rendering.

```APIDOC
## Canvas

`Canvas` is the top-level container. Styling methods set global defaults inherited by all child elements. Calling `.render()` or `.render_as_svg()` triggers layout and painting, returning an output object.

### Method Signature

```python
Canvas()
  .font_family(font_path: str | None = None)
  .font_size(size: int | float)
  .color(color: str | Color)
  .padding(padding: int | float | Padding)
  .background_color(color: str | Color | Gradient)
  .border_radius(radius: int | float | BorderRadius)
  .text_shadows(shadows: Shadow | list[Shadow])
  .render(*elements: Element | str, crop_mode: CropMode = CropMode.NONE, font_smoothing: FontSmoothing = FontSmoothing.SUBPIXEL, scale_factor: float = 1.0) -> BitmapImage
  .render_as_svg(*elements: Element | str, embed_font: bool = False) -> VectorImage
```

### Parameters for `render()`

#### Elements
- `*elements` (Element | str) - Required - Elements or strings to render.

#### Crop Mode
- `crop_mode` (CropMode) - Optional - Default: `NONE`. Controls how the output is cropped. Options: `NONE` (keeps shadow bounds), `SMART` (trims transparent pixels), `CONTENT_BOX` (crops to content).

#### Font Smoothing
- `font_smoothing` (FontSmoothing) - Optional - Default: `SUBPIXEL`. Specifies the anti-aliasing method. Options: `SUBPIXEL` (LCD) or `GRAYSCALE`.

#### Scale Factor
- `scale_factor` (float) - Optional - Default: `1.0`. Scales all dimensions proportionally for high-DPI output.

### Example

```python
from pictex import Canvas, Shadow, LinearGradient, CropMode

canvas = (
    Canvas()
    .font_family("Poppins-Bold.ttf")   # path to a .ttf/.otf file, or a system font name
    .font_size(60)
    .color("white")
    .padding(20)
    .background_color(LinearGradient(["#2C3E50", "#FD746C"]))
    .border_radius(10)
    .text_shadows(Shadow(offset=(2, 2), blur_radius=3, color="black"))
)

# Render a plain string — returns BitmapImage
image = canvas.render("Hello, World! 🎨✨")
image.save("hello.png")

# Render with scale factor for high-DPI output
hires = canvas.render("Hello!", scale_factor=2.0)
hires.save("hello_2x.png")

# Render with crop mode
smart = canvas.render("Hello!", crop_mode=CropMode.SMART)
smart.save("hello_smart.png")

# Render as SVG — returns VectorImage
svg = canvas.render_as_svg("Hello, SVG!", embed_font=True)
svg.save("hello.svg")
```
```

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

### Shadow

Source: https://github.com/francozanardi/pictex/blob/main/docs/api/models.md

Represents a shadow configuration.

```APIDOC
## class pictex.Shadow

### Description
Represents a shadow configuration.

### Parameters
(No specific parameters documented in the source for direct user invocation.)

### Request Example
(No request example provided in the source.)

### Response
(No response details provided in the source.)
```

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

### SolidColor

Source: https://github.com/francozanardi/pictex/blob/main/docs/api/models.md

Represents a solid color configuration.

```APIDOC
## class pictex.SolidColor

### Description
Represents a solid color configuration.

### Parameters
(No specific parameters documented in the source for direct user invocation.)

### Request Example
(No request example provided in the source.)

### Response
(No response details provided in the source.)
```

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

### Text Box Edge Calculation with Glyphs vs. Font Metrics

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Illustrates the difference between 'glyphs' and 'font' settings for text_box_edge, affecting bounding box calculation. Imports Canvas, Column, and Text.

```python
from pictex import Canvas, Column, Text

def example_text():
    return Text("Hello").background_color("lightgray").border(10, "red")

canvas = Canvas().font_family("Arial").font_size(80).background_color("pink")

layout = Column(
    example_text().text_box_edge("glyphs"),
    example_text().text_box_edge(bottom="glyphs", top="font"),
    example_text().text_box_edge(bottom="font", top="glyphs"),
    example_text().text_box_edge("font"),
).gap(10)

canvas.render(layout).save("text_box_edge.png")
```

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

### Save and Access SVG Content

Source: https://github.com/francozanardi/pictex/blob/main/docs/getting_started.md

Render an image as SVG using `render_as_svg()`, save the VectorImage object to a file, or access its raw SVG string.

```python
vector_image = canvas.render_as_svg(user_banner)

# Save to a file
vector_image.save("output.svg")

# Get the raw SVG string
svg_string = vector_image.svg
```

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

### Applying Two-Point Conical Gradient

Source: https://github.com/francozanardi/pictex/blob/main/docs/colors.md

Applies a TwoPointConicalGradient to the background, creating a gradient that transitions between two circles. Ensure Canvas, TwoPointConicalGradient, and Text are imported.

```python
from pictex import Canvas, TwoPointConicalGradient, Text

(Canvas()
 .background_color(TwoPointConicalGradient(colors=["yellow", "blue"], start=(0.5, 0)))
 .size(400, 400)
 .font_size(100)
 .font_family("Impact")
 .render(Text("Conical").position("center", "center"))
 .save("conical.png"))
```

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

### Fit Background Image to Element Size

Source: https://github.com/francozanardi/pictex/blob/main/docs/box_model.md

Uses the 'fit-background-image' size mode to automatically set an element's dimensions to match its background image. This is useful for containers that should be exactly the size of their background.

```python
from pictex import *

# Element will be 400x300 if the image is 400x300
card = (
    Row(Text("Content"))
    .background_image("photo.jpg")
    .fit_background_image()
    .padding(20)
)
```

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

### FontWeight

Source: https://github.com/francozanardi/pictex/blob/main/docs/api/models.md

Enumeration for font weight options.

```APIDOC
## enum pictex.FontWeight

### Description
Enumeration for font weight options.

### Parameters
(No specific parameters documented in the source for direct user invocation.)

### Request Example
(No request example provided in the source.)

### Response
(No response details provided in the source.)
```

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

### FontStyle

Source: https://github.com/francozanardi/pictex/blob/main/docs/api/models.md

Enumeration for font style options.

```APIDOC
## enum pictex.FontStyle

### Description
Enumeration for font style options.

### Parameters
(No specific parameters documented in the source for direct user invocation.)

### Request Example
(No request example provided in the source.)

### Response
(No response details provided in the source.)
```

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

### Use place() for anchor-based canvas positioning in v2.0

Source: https://github.com/francozanardi/pictex/blob/main/docs/MIGRATION.md

The `place()` method replaces the anchor-based canvas positioning behavior of the old `absolute_position()` method. It supports keywords, pixels, percentages, and offsets.

```python
Text("Overlay").place("center", "center")
```

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

### NodeType

Source: https://github.com/francozanardi/pictex/blob/main/docs/api/models.md

Enumeration for render node types.

```APIDOC
## enum pictex.NodeType

### Description
Enumeration for render node types, indicating the type of rendered element.

### Parameters
(No specific parameters documented in the source for direct user invocation.)

### Request Example
(No request example provided in the source.)

### Response
(No response details provided in the source.)
```

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

### Apply Multiple Gradients to Text Elements

Source: https://github.com/francozanardi/pictex/blob/main/docs/colors.md

Use SweepGradient for background, LinearGradient for text fill, RadialGradient for stroke, and another LinearGradient for underline. Ensure gradients are defined before applying them to the canvas elements.

```python
from pictex import Canvas, LinearGradient, RadialGradient, SweepGradient

background_gradient = SweepGradient(colors=["pink", "beige", "pink"])
text_gradient = LinearGradient(colors=["#FFD700", "#FF6B6B"])
stroke_gradient = RadialGradient(colors=["#4A00E0", "#8E2DE2"])
underline_gradient = LinearGradient(
    colors=["#00F260", "#0575E6"],
    start_point=(0.5, 0.0),
    end_point=(0.5, 1.0)
)
border_gradient = LinearGradient(colors=["blue", "darkcyan"])

canvas = (
    Canvas()
    .font_family("Impact")
    .font_size(150)
    .color(text_gradient)
    .background_color(background_gradient)
    .text_stroke(width=8, color=stroke_gradient)
    .underline(thickness=15, color=underline_gradient)
    .border(width=10, color=border_gradient)
    .padding(30)
)

canvas.render("GRADIENTS!").save("gradients_everywhere.png")
```

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

### TextAlign

Source: https://github.com/francozanardi/pictex/blob/main/docs/api/models.md

Enumeration for text alignment options.

```APIDOC
## enum pictex.TextAlign

### Description
Enumeration for text alignment options.

### Parameters
(No specific parameters documented in the source for direct user invocation.)

### Request Example
(No request example provided in the source.)

### Response
(No response details provided in the source.)
```

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

### Render Text with Complex Script Support

Source: https://github.com/francozanardi/pictex/blob/main/docs/text.md

Display text in complex scripts like Arabic, where characters connect and change forms based on context. Text shaping handles these transformations automatically.

```python
from pictex import Canvas, NamedColor

(
    Canvas()
    .font_size(100)
    .background_color(NamedColor.BEIGE)
    .color(NamedColor.DARKGREEN)
    .render("كتاب")
    .save("docs-arabic.png")
)
```

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

### Cross Axis Alignment with align-items

Source: https://github.com/francozanardi/pictex/blob/main/docs/core_concepts.md

Demonstrates different align-items values for positioning children along the cross axis within a Row.

```python
from pictex import *

def create_alignment_example(align):
    row_with_alignment = Row(
        Text("A").background_color("blue").font_size(80),
        Text("B").background_color("red").font_size(65),
        Text("C").background_color("green").font_size(50),
    ).align_items(align).border(4, "black").gap(30)
    return Column(
        Text(align).font_size(40),
        row_with_alignment
    ).background_color("pink")

aligns = [
    "start",
    "center",
    "end",
    "stretch"
]
examples = []
for a in aligns:
    examples.append(create_alignment_example(a))

image = Canvas().font_size(80).render(Column(*examples).gap(20))
image.save("alignment.png")
```

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

### Generate Tweet Card Image

Source: https://context7.com/francozanardi/pictex/llms.txt

Demonstrates creating a complex image layout using nested Rows and Columns, styling text, images, and borders, suitable for social media cards.

```python
from pictex import Canvas, Row, Column, Text, Image

AVATAR      = "avatar.jpg"
NAME        = "Marin Mersenne"
HANDLE      = "@marin.mersenne"
TWEET_TEXT  = "Spent all week calculating 2⁶⁷-1 by hand only to find it's composite."

def stat(icon: str, count: str) -> Row:
    return Row(
        Text(icon).font_size(16),
        Text(count).font_size(15).color("#536471"),
    ).align_items("center").gap(2)

tweet_card = (
    Column(
        Row(
            Image(AVATAR).size(50, 50).border_radius("50%"),
            Column(
                Text(NAME).font_size(16).font_weight(700),
                Text(HANDLE).font_size(15).color("#536471"),
            ).gap(2)
        ).align_items("center").gap(12),
        Text(TWEET_TEXT).font_size(18).line_height(1.4),
        Row(
            stat("💬", "31"),
            stat("🔁", "127"),
            stat("❤", "1.9K"),
        ).size(width="100%").justify_content("space-between"),
    )
    .size(width=600)
    .background_color("white")
    .padding(25).gap(15)
    .border_radius(16)
    .border(1, "#CFD9DE")
)

Canvas().font_family("Arial").background_color("#E9ECEF").padding(50).render(tweet_card).save("tweet.png")
```

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

### RenderNode

Source: https://github.com/francozanardi/pictex/blob/main/docs/api/models.md

Represents a node in the render tree.

```APIDOC
## class pictex.RenderNode

### Description
Represents a node in the render tree, providing access to the hierarchical structure of rendered elements.

### Parameters
(No specific parameters documented in the source for direct user invocation.)

### Request Example
(No request example provided in the source.)

### Response
(No response details provided in the source.)
```

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

### Create a Rounded Border Circle

Source: https://github.com/francozanardi/pictex/blob/main/docs/box_model.md

Applies a solid border and rounded corners to create a circular element. Ensure the canvas is rendered and saved to a file.

```python
from pictex import *

Canvas().render(
    Row()
    .size(100, 100)
    .background_color("green")
    .border(3, "black")
    .border_radius("50%")
).save("circle.png")
```

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

### Applying Radial Gradient

Source: https://github.com/francozanardi/pictex/blob/main/docs/colors.md

Applies a RadialGradient to the background. The gradient transitions from inner to outer colors in a circular pattern. Ensure Canvas and RadialGradient are imported.

```python
from pictex import Canvas, RadialGradient

(Canvas()
 .background_color(RadialGradient(["yellow", "orange", "purple"]))
 .font_size(150)
 .font_family("Impact")
 .color("beige")
 .text_stroke(4, "black")
 .padding(30)
 .render("Radial")
 .save("radial.png"))
```