### Render Image to ANSI String Output

Source: https://context7.com/eliukblau/pixterm/llms.txt

Use Render() to get the ANSI escape code string for an image. RenderExt() provides options to output Go code or disable background colors in dithering mode.

```go
package main

import (
    "fmt"
    "image/color"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    bg := color.RGBA{0, 0, 0, 255}

    img, err := ansimage.NewScaledFromFile(
        "image.png",
        20, 40,
        bg,
        ansimage.ScaleModeFit,
        ansimage.DitheringWithBlocks,
    )
    if err != nil {
        panic(err)
    }

    // Get basic ANSI string
    ansiStr := img.Render()
    fmt.Print(ansiStr)

    // Get extended render with options:
    // renderGoCode: output as Go fmt.Print() code
    // disableBgColor: disable background in dithering mode
    goCode := img.RenderExt(true, false)  // Go code output
    noBgRender := img.RenderExt(false, true) // No background color

    // Save Go code to file
    // os.WriteFile("image_render.go", []byte(goCode), 0644)

    // Render without background
    fmt.Print(noBgRender)
}
```

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

### Load ANSImage From File

Source: https://context7.com/eliukblau/pixterm/llms.txt

Initialize an ANSImage instance directly from a file path with support for multiple image formats.

```go
package main

import (
    "image/color"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    // Black matte color for transparency
    bg := color.RGBA{0, 0, 0, 255}

    // Load image without dithering (classic mode)
    img, err := ansimage.NewFromFile("photo.png", bg, ansimage.NoDithering)
    if err != nil {
        panic(err)
    }

    // Enable parallel rendering
    img.SetMaxProcs(runtime.NumCPU())

    // Draw to terminal
    img.Draw()
}
```

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

### Advanced CLI Configuration

Source: https://context7.com/eliukblau/pixterm/llms.txt

Commands for setting matte colors, terminal dimensions, and exporting rendered output.

```bash
# Set matte/background color (hex format, default: 000000)
pixterm -m ff5500 transparent.png

# Disable background color in dithering mode
pixterm -d 1 -nobg image.png

# Set custom terminal size (rows and columns)
pixterm -tr 40 -tc 100 image.png

# Output as Go code for embedding
pixterm -go image.png > image_render.go

# Show version
pixterm -version

# Show credits
pixterm -credits
```

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

### Load Image From io.Reader with Pixterm

Source: https://context7.com/eliukblau/pixterm/llms.txt

Use NewFromReader to create an ANSImage from any io.Reader, suitable for reading image data from files or network streams. Requires reading data into a buffer first.

```go
package main

import (
    "bytes"
    "image/color"
    "os"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    // Read image data into buffer
    data, err := os.ReadFile("image.png")
    if err != nil {
        panic(err)
    }

    reader := bytes.NewReader(data)
    bg := color.RGBA{0, 0, 0, 255}

    img, err := ansimage.NewFromReader(reader, bg, ansimage.NoDithering)
    if err != nil {
        panic(err)
    }

    img.SetMaxProcs(runtime.NumCPU())
    img.Draw()
}
```

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

### Display Images via CLI

Source: https://context7.com/eliukblau/pixterm/llms.txt

Basic commands for rendering local or remote images with dithering and scaling options.

```bash
# Display a local image file
pixterm image.png

# Display image from URL
pixterm https://example.com/photo.jpg

# Display with specific dithering mode
# 0 = no dithering (default), 1 = with blocks, 2 = with chars
pixterm -d 1 image.png

# Display with custom scale method
# 0 = resize (default), 1 = fill, 2 = fit
pixterm -s 2 image.png
```

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

### Image Scaling Modes in Go

Source: https://context7.com/eliukblau/pixterm/llms.txt

Demonstrates ScaleModeResize, ScaleModeFill, and ScaleModeFit for scaling images to terminal dimensions. Use ScaleModeResize for exact dimensions, ScaleModeFill to maintain aspect ratio and crop, and ScaleModeFit to maintain aspect ratio with potential empty space. Requires importing the 'ansimage' package.

```go
package main

import (
    "fmt"
    "image/color"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    bg := color.RGBA{0, 0, 0, 255}
    filename := "wide_photo.jpg"
    rows, cols := 24, 80

    // ScaleModeResize: Stretches image to exact dimensions
    // May distort aspect ratio
    imgResize, _ := ansimage.NewScaledFromFile(
        filename, rows, cols, bg,
        ansimage.ScaleModeResize,
        ansimage.NoDithering,
    )

    // ScaleModeFill: Scales and crops to fill area
    // Maintains aspect ratio, may crop edges
    imgFill, _ := ansimage.NewScaledFromFile(
        filename, rows, cols, bg,
        ansimage.ScaleModeFill,
        ansimage.NoDithering,
    )

    // ScaleModeFit: Scales to fit within area
    // Maintains aspect ratio, may have empty space
    imgFit, _ := ansimage.NewScaledFromFile(
        filename, rows, cols, bg,
        ansimage.ScaleModeFit,
        ansimage.NoDithering,
    )

    fmt.Printf("Resize: %dx%d\n", imgResize.Width(), imgResize.Height())
    fmt.Printf("Fill: %dx%d\n", imgFill.Width(), imgFill.Height())
    fmt.Printf("Fit: %dx%d\n", imgFit.Width(), imgFit.Height())
}
```

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

### Load and Scale ANSImage

Source: https://context7.com/eliukblau/pixterm/llms.txt

Create an ANSImage from a file with specific target dimensions and scaling modes.

```go
package main

import (
    "image/color"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    bg := color.RGBA{0, 0, 0, 255}

    // Scale modes:
    // ScaleModeResize - full scale to area
    // ScaleModeFill   - resize and crop with center anchor
    // ScaleModeFit    - resize to fit, preserving aspect ratio

    // Load and scale to 48 rows x 80 columns with fit mode
    img, err := ansimage.NewScaledFromFile(
        "photo.jpg",
        48,                       // target height (rows)
        80,                       // target width (columns)
        bg,                       // background/matte color
        ansimage.ScaleModeFit,    // scale mode
        ansimage.NoDithering,     // dithering mode
    )
    if err != nil {
        panic(err)
    }

    img.SetMaxProcs(runtime.NumCPU())
    img.Draw()
}
```

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

### Load Image From URL with Pixterm

Source: https://context7.com/eliukblau/pixterm/llms.txt

Use NewFromURL to fetch and convert an image directly from an HTTP/HTTPS URL. Handles potential download or network errors.

```go
package main

import (
    "image/color"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    bg := color.RGBA{0, 0, 0, 255}

    // Load image from URL
    img, err := ansimage.NewFromURL(
        "https://example.com/image.png",
        bg,
        ansimage.NoDithering,
    )
    if err != nil {
        // Handle ErrImageDownloadFailed or network errors
        panic(err)
    }

    img.SetMaxProcs(runtime.NumCPU())
    img.Draw()
}
```

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

### Create Empty ANSImage

Source: https://context7.com/eliukblau/pixterm/llms.txt

Initialize a blank canvas for manual pixel manipulation using the ansimage package.

```go
package main

import (
    "fmt"
    "image/color"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    // Create a 20x40 ANSImage with black background and no dithering
    bg := color.RGBA{0, 0, 0, 255}
    img, err := ansimage.New(20, 40, bg, ansimage.NoDithering)
    if err != nil {
        panic(err)
    }

    // Set individual pixels (y, x, r, g, b, brightness)
    for y := 0; y < img.Height(); y++ {
        for x := 0; x < img.Width(); x++ {
            // Create a gradient pattern
            r := uint8(x * 255 / img.Width())
            g := uint8(y * 255 / img.Height())
            img.SetAt(y, x, r, g, 128, 128)
        }
    }

    // Render to terminal
    img.Draw()

    fmt.Printf("Image size: %dx%d\n", img.Width(), img.Height())
}
```

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

### Load and Scale Image From URL with Pixterm

Source: https://context7.com/eliukblau/pixterm/llms.txt

NewScaledFromURL fetches an image from a URL and scales it to specified dimensions, supporting different scaling modes and dithering options.

```go
package main

import (
    "image/color"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    bg := color.RGBA{32, 32, 32, 255} // Dark gray background

    // Load, scale, and apply dithering with blocks
    img, err := ansimage.NewScaledFromURL(
        "https://example.com/photo.jpg",
        64,                           // height
        120,                          // width
        bg,
        ansimage.ScaleModeFill,       // fill mode crops to fit
        ansimage.DitheringWithBlocks, // use block characters
    )
    if err != nil {
        panic(err)
    }

    img.SetMaxProcs(runtime.NumCPU())
    img.Draw()
}
```

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

### Load and Scale Image From io.Reader with Pixterm

Source: https://context7.com/eliukblau/pixterm/llms.txt

NewScaledFromReader creates a scaled ANSImage from an io.Reader, allowing control over dimensions, scaling mode, and dithering. Ensure the reader is properly closed using defer.

```go
package main

import (
    "image/color"
    "os"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    file, err := os.Open("photo.jpg")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    bg := color.RGBA{255, 255, 255, 255} // White background

    img, err := ansimage.NewScaledFromReader(
        file,
        32,                          // height
        64,                          // width
        bg,
        ansimage.ScaleModeResize,    // full resize to dimensions
        ansimage.DitheringWithChars, // ASCII character dithering
    )
    if err != nil {
        panic(err)
    }

    img.SetMaxProcs(runtime.NumCPU())
    img.Draw()
}
```

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

### Create ANSImage From image.Image with Pixterm

Source: https://context7.com/eliukblau/pixterm/llms.txt

NewFromImage converts a standard Go image.Image into an ANSImage. This is useful for integrating with existing image processing pipelines or programmatically generated images.

```go
package main

import (
    "image"
    "image/color"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    // Create a simple gradient image programmatically
    width, height := 80, 40
    img := image.NewRGBA(image.Rect(0, 0, width, height))

    for y := 0; y < height; y++ {
        for x := 0; x < width; x++ {
            r := uint8(x * 255 / width)
            g := uint8(y * 255 / height)
            b := uint8(128)
            img.Set(x, y, color.RGBA{r, g, b, 255})
        }
    }

    bg := color.RGBA{0, 0, 0, 255}

    // Convert to ANSImage
    ansImg, err := ansimage.NewFromImage(img, bg, ansimage.NoDithering)
    if err != nil {
        panic(err)
    }

    ansImg.SetMaxProcs(runtime.NumCPU())
    ansImg.Draw()
}
```

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

### ansimage.New

Source: https://context7.com/eliukblau/pixterm/llms.txt

Creates a new empty ANSImage instance for manual pixel manipulation.

```APIDOC
## func ansimage.New

### Description
Creates a new empty ANSImage with specified dimensions and background color ready for manual pixel manipulation.

### Parameters
- **rows** (int) - Required - Target height in rows
- **cols** (int) - Required - Target width in columns
- **bg** (color.RGBA) - Required - Background/matte color
- **dithering** (int) - Required - Dithering mode (e.g., ansimage.NoDithering)

### Response
- **img** (*ANSImage) - The initialized ANSImage object
- **err** (error) - Error if initialization fails
```

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

### ansimage.NewFromFile

Source: https://context7.com/eliukblau/pixterm/llms.txt

Loads an image from a file path and converts it to an ANSImage.

```APIDOC
## func ansimage.NewFromFile

### Description
Create an ANSImage directly from a file path with support for JPEG, PNG, GIF, BMP, TIFF, and WebP formats.

### Parameters
- **path** (string) - Required - Path to the image file
- **bg** (color.RGBA) - Required - Background/matte color
- **dithering** (int) - Required - Dithering mode

### Response
- **img** (*ANSImage) - The loaded ANSImage object
- **err** (error) - Error if loading fails
```

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

### Direct Pixel Manipulation with SetAt and GetAt

Source: https://context7.com/eliukblau/pixterm/llms.txt

Create or modify images by setting individual pixel colors and brightness using SetAt(y, x, r, g, b, brightness). Retrieve pixel data with GetAt(y, x) and render a single pixel to an ANSI string.

```go
package main

import (
    "fmt"
    "image/color"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    bg := color.RGBA{0, 0, 0, 255}

    // Create empty ANSImage
    img, _ := ansimage.New(20, 40, bg, ansimage.NoDithering)

    // Set pixels to create a pattern
    for y := 0; y < img.Height(); y++ {
        for x := 0; x < img.Width(); x++ {
            // SetAt(y, x, r, g, b, brightness)
            if (x+y)%2 == 0 {
                img.SetAt(y, x, 255, 0, 0, 200) // Red
            } else {
                img.SetAt(y, x, 0, 0, 255, 200) // Blue
            }
        }
    }

    // Read pixel data
    pixel, err := img.GetAt(10, 20)
    if err != nil {
        panic(err) // ErrOutOfBounds if coordinates invalid
    }

    fmt.Printf("Pixel at (10,20): R=%d G=%d B=%d Brightness=%d\n",
        pixel.R, pixel.G, pixel.B, pixel.Brightness)

    // Render individual pixel as ANSI string
    ansiPixel := pixel.Render()
    fmt.Print(ansiPixel)

    img.Draw()
}
```

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

### Create Scaled ANSImage From image.Image with Pixterm

Source: https://context7.com/eliukblau/pixterm/llms.txt

NewScaledFromImage converts and scales a standard Go image.Image to specified terminal dimensions. It supports various scaling modes and dithering options for optimal display.

```go
package main

import (
    "image"
    "image/color"
    "image/png"
    "os"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    // Load image using standard library
    file, _ := os.Open("large_photo.png")
    defer file.Close()

    img, _ := png.Decode(file)

    bg := color.RGBA{0, 0, 0, 255}

    // Scale down for terminal display
    ansImg, err := ansimage.NewScaledFromImage(
        img,
        24,                       // terminal rows
        80,                       // terminal columns
        bg,
        ansimage.ScaleModeFit,    // preserve aspect ratio
        ansimage.NoDithering,
    )
    if err != nil {
        panic(err)
    }

    ansImg.SetMaxProcs(runtime.NumCPU())
    ansImg.Draw()
}
```

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

### Dithering Modes for Image Rendering

Source: https://context7.com/eliukblau/pixterm/llms.txt

Explore three dithering modes: NoDithering (half blocks), DitheringWithBlocks (shade blocks), and DitheringWithChars (ASCII characters). Each mode offers a different visual style suitable for various image types and terminal fonts.

```go
package main

import (
    "fmt"
    "image/color"
    "runtime"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    bg := color.RGBA{0, 0, 0, 255}
    filename := "photo.jpg"

    // Mode 0: NoDithering (Classic) - Uses half block elements
    // Best for detailed images, requires terminal font with Unicode blocks
    imgClassic, _ := ansimage.NewScaledFromFile(
        filename, 24, 80, bg,
        ansimage.ScaleModeFit,
        ansimage.NoDithering,
    )

    // Mode 1: DitheringWithBlocks - Uses shade block characters
    // Creates artistic block-style rendering
    imgBlocks, _ := ansimage.NewScaledFromFile(
        filename, 24, 80, bg,
        ansimage.ScaleModeFit,
        ansimage.DitheringWithBlocks,
    )

    // Mode 2: DitheringWithChars - Uses ASCII characters
    // Works with any font, ASCII art style
    imgChars, _ := ansimage.NewScaledFromFile(
        filename, 24, 80, bg,
        ansimage.ScaleModeFit,
        ansimage.DitheringWithChars,
    )

    // Display each mode
    for _, img := range []*ansimage.ANSImage{imgClassic, imgBlocks, imgChars} {
        ansimage.ClearTerminal()
        img.SetMaxProcs(runtime.NumCPU())
        img.Draw()
        fmt.Println("\nPress Enter for next mode...")
        fmt.Scanln()
    }
}
```

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

### ansimage.NewScaledFromFile

Source: https://context7.com/eliukblau/pixterm/llms.txt

Loads an image from a file and scales it to specific dimensions.

```APIDOC
## func ansimage.NewScaledFromFile

### Description
Create a scaled ANSImage from a file with configurable scale mode (resize, fill, or fit).

### Parameters
- **path** (string) - Required - Path to the image file
- **rows** (int) - Required - Target height in rows
- **cols** (int) - Required - Target width in columns
- **bg** (color.RGBA) - Required - Background/matte color
- **scaleMode** (int) - Required - Scaling strategy (ScaleModeResize, ScaleModeFill, ScaleModeFit)
- **dithering** (int) - Required - Dithering mode

### Response
- **img** (*ANSImage) - The scaled ANSImage object
- **err** (error) - Error if loading or scaling fails
```

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

### Clear Terminal for Animation

Source: https://context7.com/eliukblau/pixterm/llms.txt

Use ansimage.ClearTerminal() to clear the terminal screen before drawing each frame in an animation loop. This ensures a clean display for sequential image rendering.

```go
package main

import (
    "image/color"
    "time"

    "github.com/eliukblau/pixterm/pkg/ansimage"
)

func main() {
    bg := color.RGBA{0, 0, 0, 255}
    images := []string{"frame1.png", "frame2.png", "frame3.png"}

    // Simple animation loop
    for _, filename := range images {
        ansimage.ClearTerminal() // Clear screen before drawing

        img, err := ansimage.NewScaledFromFile(
            filename, 24, 80, bg,
            ansimage.ScaleModeFit,
            ansimage.NoDithering,
        )
        if err != nil {
            continue
        }

        img.Draw()
        time.Sleep(100 * time.Millisecond)
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.