Image Toolbox

https://github.com/t8rin/imagetoolbox
Admin
Image Toolbox is a comprehensive Android image editor featuring 300+ filters, batch processing, AI...
Tokens:20,832
Snippets:255
Trust Score:10
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Image Format Enumeration and Properties

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Shows how to use the `ImageFormat` sealed class to represent supported output formats. Includes examples of selecting formats by MIME type, checking lossless properties, and accessing all supported formats.

```kotlin
// Select format from MIME type string
val format: ImageFormat = ImageFormat["image/avif"] // -> ImageFormat.Avif.Lossless

// Check if format is lossless
println(ImageFormat.Png.Lossless.isLossless) // true
println(ImageFormat.Jxl.Lossy.isLossless)   // false

// Supported formats (all entries)
val allFormats: List<ImageFormat> = ImageFormat.entries
// [Jpg, Jpeg, MozJpeg, Jpegli, Png.Lossless, Png.Lossy, OxiPNG,
//  Bmp, Webp.Lossless, Webp.Lossy, Avif.Lossless, Avif.Lossy,
//  Heic.Lossless, Heic.Lossy, Heif.Lossless, Heif.Lossy,
//  Jxl.Lossless, Jxl.Lossy, Tif, Tiff, Jp2, J2k, Qoi, Ico, Gif]
```

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

### Clone ImageToolbox Repository

Source: https://github.com/t8rin/imagetoolbox/blob/master/README.md

Use this command to clone the ImageToolbox repository from GitHub. Ensure you have Git installed.

```bash
git clone https://github.com/yourusername/ImageToolbox.git
```

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

### HashingType: Registering and Using Custom Hash Algorithms

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Shows how to register custom hashing providers and use built-in HashingType enums for file checksum computation. Custom providers must be registered once at process start.

```kotlin
// Register custom providers once at app startup
HashingType.registerSecurityMessageDigests(
    Security.getAlgorithms("MessageDigest").toList()
)

// Use built-in types directly
val md5 = HashingType.MD5        // digest = "MD5"
val sha256 = HashingType.SHA_256 // digest = "SHA-256"

// Retrieve all available algorithms
val all: List<HashingType> = HashingType.entries
// [MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, …(BouncyCastle algorithms)]

// Look up by digest string
val found: HashingType? = HashingType.fromString("SHA-512")

// Compute a hash (actual digest logic lives in the data layer)
// The ChecksumTools feature uses HashingType to calculate file checksums
// via FileController.readBytes() and MessageDigest.getInstance(type.digest)
```

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

### Create and Manage Template Filters

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Defines how to create reusable `TemplateFilter` objects, which bundle multiple `Filter` instances. Includes examples of checking equality and saving templates.

```kotlin
// Create a custom "Retro Film" template
val retroFilm = TemplateFilter(
    name = "Retro Film",
    filters = listOf(
        SepiaFilterImpl(),
        SaturationFilterImpl(0.8f),
        GrainFilterImpl(value = 0.15f),
        VignetteFilterImpl(value = Triple(0.4f, 0.7f, ColorModel(0xFF000000))),
    )
)

// Check equality (order-independent, compares by class name + value)
val another = TemplateFilter(name = "Retro Film", filters = listOf(SepiaFilterImpl()))
println(retroFilm == another) // false — different filter count
```

```kotlin
// Use FilterParamsInteractor to persist/load templates
// (injected interface backed by DataStore)
suspend fun saveTemplate(
    interactor: FilterParamsInteractor,
    template: TemplateFilter
) {
    interactor.saveTemplateFilter(template)
}
```

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

### Update Local Copy with Upstream Changes

Source: https://github.com/t8rin/imagetoolbox/wiki/Contributing-Guidelines

Update your local repository copy with the latest changes from the upstream repository before starting new work. Ensure you are on the correct branch.

```bash
git remote update
git checkout <branch-name>
git rebase upstream/<branch-name>
```

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

### Set Upstream Remote and Update Local Copy

Source: https://github.com/t8rin/imagetoolbox/blob/master/CONTRIBUTING.md

Add the original repository as an 'upstream' remote and update your local copy before starting work. This ensures you have the latest changes from the main project.

```bash
cd <repo-name>  
git remote add upstream https://github.com/<upstream-owner>/<ImageToolbox>
git remote -v # To the check the remotes for this repository 
```

```bash
git remote update
git checkout <branch-name>
git rebase upstream/<branch-name>
```

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

### SettingsProvider: Observing App Settings

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Demonstrates how to observe the current app settings using SettingsProvider. This is useful for reacting to changes in user preferences, such as theme or dynamic color settings.

```kotlin
// Observe current settings (via SettingsProvider → Flow<SettingsState>)
settingsProvider.getSettingsState().collect { state: SettingsState ->
    println("Theme: ${state.nightMode}")          // NightMode.System / Light / Dark
    println("Dynamic colors: ${state.isDynamicColors}")
    println("AMOLED: ${state.isAmoledMode}")
    println("Font: ${state.font}")
    println("Default format: ${state.defaultImageFormat}")
    println("Default scale: ${state.defaultImageScaleMode}")
    println("Save folder: ${state.saveFolderUri}")
    println("Presets: ${state.presets}")
}
```

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

### Create and Switch to a New Branch

Source: https://github.com/t8rin/imagetoolbox/wiki/Contributing-Guidelines

Create a new branch for your work and switch to it. Name the branch descriptively to identify the issue it addresses.

```bash
# It will create a new branch with name branch_name and switch to that branch 
git checkout -b branch_name
```

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

### Build ImageToolbox Project

Source: https://github.com/t8rin/imagetoolbox/blob/master/README.md

Build the ImageToolbox project using the Gradle wrapper. This command compiles the project and prepares it for execution.

```bash
./gradlew build
```

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

### Configure Image Compression Quality

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Illustrates how to configure specific quality settings for different image formats like JXL, AVIF, PNG, and TIFF. Demonstrates using `Quality` objects and coercing values into valid ranges.

```kotlin
// Format-specific quality configuration
val jxlQuality = Quality.Jxl(
    qualityValue = 85,   // 1–100
    effort = 5,          // 1–10 (encoding speed vs. compression)
    speed = 2,           // 0–4
    channels = Quality.Channels.RGBA
)
val avifQuality = Quality.Avif(qualityValue = 70, effort = 6)
val pngLossy = Quality.PngLossy(maxColors = 256, compressionLevel = 7)
val tiffQuality = Quality.Tiff(compressionScheme = 5) // LZW

// Coerce quality values into valid ranges for the chosen format
val coerced = jxlQuality.coerceIn(ImageFormat.Jxl.Lossy)
```

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

### Resize Images with ImageScaler

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Illustrates resizing images using the ImageScaler interface with various modes and algorithms. Supports explicit dimensions, flexible resizing while maintaining aspect ratio, center-cropping, and scaling down to safe display sizes. Requires an instance of ImageScaler.

```kotlin
suspend fun resizeImage(
    imageScaler: ImageScaler<Bitmap>,
    bitmap: Bitmap
): Bitmap {
    // Explicit resize to 1920×1080 using Lanczos3 in Oklab color space
    val resized = imageScaler.scaleImage(
        image = bitmap,
        width = 1920,
        height = 1080,
        resizeType = ResizeType.Explicit,
        imageScaleMode = ImageScaleMode.Lanczos3(
            scaleColorSpace = ScaleColorSpace.OklabSRGB
        )
    )

    // Flexible resize — keeps aspect ratio, fits within given bounds
    val flexible = imageScaler.scaleImage(
        image = bitmap,
        width = 800,
        height = 600,
        resizeType = ResizeType.Flexible(resizeAnchor = ResizeAnchor.Default)
    )

    // Center-crop with blurred background fill
    val cropped = imageScaler.scaleImage(
        image = bitmap,
        width = 1080,
        height = 1080,
        resizeType = ResizeType.CenterCrop(
            canvasColor = 0xFF000000.toInt(),
            blurRadius = 35,
            scaleFactor = 1f,
            position = Position.Center
        )
    )

    // Scale down until the image can be displayed in memory safely
    return imageScaler.scaleUntilCanShow(bitmap) ?: bitmap
}
```

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

### Clone the ImageToolbox Repository

Source: https://github.com/t8rin/imagetoolbox/wiki/Contributing-Guidelines

Clone your forked repository to your local machine. Replace `<your-username>` and `<ImageToolbox>` with your GitHub username and the repository name.

```bash
git clone https://github.com/<your-username>/<ImageToolbox>  
```

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

### Run ImageToolbox Application

Source: https://github.com/t8rin/imagetoolbox/blob/master/README.md

Execute the ImageToolbox application after building it. This command uses the Gradle wrapper to run the application.

```bash
./gradlew run
```

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

### Add Upstream Remote and Check Remotes

Source: https://github.com/t8rin/imagetoolbox/wiki/Contributing-Guidelines

Add a reference to the original project as 'upstream' and verify the configured remotes. Replace `<upstream-owner>` and `<ImageToolbox>` with the original owner's username and the repository name.

```bash
cd <repo-name>  
git remote add upstream https://github.com/<upstream-owner>/<ImageToolbox>
git remote -v # To the check the remotes for this repository 
```

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

### Create and Use Resize Presets

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Define and use named presets for common image resizing operations. Presets can be serialized to strings for persistence and parsed back into lists.

```kotlin
// Percentage-based scaling (relative to original)
val half = Preset.Percentage(50)
val quarter = Preset.Percentage(25)
val original = Preset.Original // Percentage(100)

// Fixed aspect ratio preset
val widescreen = Preset.AspectRatio(ratio = 16f / 9f, isFit = false)

// Telegram sticker preset (512×512 max, lossless PNG)
val telegram = Preset.Telegram

// Serialize to string for DataStore persistence
val str = half.asString()        // "50%"
val ratioStr = widescreen.asString() // "ratio(1.7777778)"

// Parse list from stored settings string
val presets: List<Preset>? = Preset.createListFromInts("25*50*75*100")
// -> [Percentage(25), Percentage(50), Percentage(75), Percentage(100)]

// Apply preset via ImageTransformer
suspend fun applyPreset(
    transformer: ImageTransformer<Bitmap>,
    bitmap: Bitmap,
    currentInfo: ImageInfo
): ImageInfo {
    return transformer.applyPresetBy(
        image = bitmap,
        preset = Preset.Percentage(50),
        currentInfo = currentInfo
    )
}
```

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

### Load Images with ImageGetter

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Demonstrates loading images from various sources using the ImageGetter interface. Supports full-resolution loading, thumbnail generation, and applying transformations during decoding. Ensure ImageGetter is injected via Hilt.

```kotlin
class MyComponent @AssistedInject constructor(
    private val imageGetter: ImageGetter<Bitmap>
) {
    // Load full-resolution image with metadata
    suspend fun loadImage(uri: String): ImageData<Bitmap>? {
        return imageGetter.getImage(
            uri = uri,
            originalSize = true,
            onFailure = { throwable -> Log.e("IMG", "Load failed", throwable) }
        )
        // Returns ImageData<Bitmap> containing:
        //   .image     -> Bitmap
        //   .imageInfo -> ImageInfo (width, height, format, quality, …)
        //   .metadata  -> Exif Metadata?
    }

    // Load a thumbnail (down-sampled to fit within 512 px)
    suspend fun loadThumbnail(uri: String): Bitmap? {
        return imageGetter.getImage(data = uri, size = 512)
    }

    // Load with applied filter transformations
    suspend fun loadWithFilters(
        uri: String,
        filters: List<Transformation<Bitmap>>
    ): ImageData<Bitmap>? {
        return imageGetter.getImageWithTransformations(
            uri = uri,
            transformations = filters,
            originalSize = false
        )
    }
}
```

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

### Share and Cache Images with ImageShareProvider

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Utilize ImageShareProvider to share single images via the system share sheet, cache images to temporary directories for previews, and share multiple URIs with progress tracking. Provide an imageLoader for loading images from URIs when sharing batches.

```kotlin
suspend fun shareImage(
    shareProvider: ImageShareProvider<Bitmap>,
    bitmap: Bitmap,
    info: ImageInfo
) {
    // Share a single image via the system share sheet
    shareProvider.shareImage(
        imageInfo = info,
        image = bitmap,
        onComplete = { println("Share dialog dismissed") }
    )

    // Cache an image and get its content URI for use in other apps
    val cachedUri: String? = shareProvider.cacheImage(
        image = bitmap,
        imageInfo = info,
        filename = "preview_output"
    )
    // cachedUri -> "content://com.t8rin.imagetoolbox.fileprovider/cache/preview_output.jpg"

    // Share a list of URIs with progress tracking
    shareProvider.shareImages(
        uris = listOf("content://uri1", "content://uri2", "content://uri3"),
        imageLoader = { uri ->
            val data = imageGetter.getImage(uri)
            data?.let { Pair(it.image, it.imageInfo) }
        },
        onProgressChange = { progress -> println("Sharing: $progress%") }
    )
}
```

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

### PdfManager: Comprehensive PDF Manipulation

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Demonstrates various PDF operations using the PdfManager API, including creation from images, page extraction, merging, rotation, protection, compression, watermarking, creating searchable PDFs, and metadata editing. Ensure PdfManager is properly initialized before use.

```kotlin
suspend fun workWithPdfs(pdfManager: PdfManager) {
    // Convert images to PDF
    val pdfUri: String = pdfManager.createPdf(
        imageUris = listOf("content://uri1.jpg", "content://uri2.png"),
        params = PdfCreationParams(quality = 90)
    )

    // Extract all pages as images (streaming)
    pdfManager.extractPages(
        uri = pdfUri,
        params = PdfExtractPagesParams(pages = null) // null = all pages
    ).collect {
        when (it) {
            is ExtractPagesAction.Complete -> println("Done: ${it.resultUri}")
            is ExtractPagesAction.Page -> println("Page ${it.pageIndex}: ${it.uri}")
        }
    }

    // Merge multiple PDFs into one
    val merged: String = pdfManager.mergePdfs(
        uris = listOf("content://doc1.pdf", "content://doc2.pdf")
    )

    // Rotate specific pages (indices 0-based, degrees: 0,90,180,270)
    val rotated: String = pdfManager.rotatePdf(
        uri = pdfUri,
        rotations = listOf(0, 90, 0, 270) // one angle per page
    )

    // Password-protect a PDF
    val protected: String = pdfManager.protectPdf(uri = pdfUri, password = "s3cr3t")

    // Compress PDF (quality 0.0–1.0)
    val compressed: String = pdfManager.compressPdf(uri = pdfUri, quality = 0.7f)

    // Add watermark
    val watermarked: String = pdfManager.addWatermark(
        uri = pdfUri,
        params = PdfWatermarkParams(/* text, opacity, position, … */)
    )

    // OCR: create searchable PDF from recognized-text pages
    val searchable: String = pdfManager.createSearchablePdf(
        pages = listOf(
            SearchablePdfPage(imageUri = "content://scan.jpg", recognizedText = "Hello World")
        )
    )

    // Get and update metadata
    val meta: PdfMetadata = pdfManager.getPdfMetadata(uri = pdfUri)
    pdfManager.changePdfMetadata(
        uri = pdfUri,
        metadata = meta.copy(author = "T8RIN", title = "My Document")
    )
}
```

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

### Define Resize Strategies with ResizeType

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Configure image resizing behavior using ResizeType. Choose from exact pixel dimensions, fitting within bounds while preserving aspect ratio, center-cropping with customizable backgrounds, or fitting with letterboxing. These types integrate with ImageScaler.

```kotlin
// Exact pixel dimensions (ignores aspect ratio)
val explicit = ResizeType.Explicit
```

```kotlin
// Fit within bounds while preserving aspect ratio
val flexible = ResizeType.Flexible(resizeAnchor = ResizeAnchor.Default)
```

```kotlin
// Center-crop to exact output size with configurable background
val centerCrop = ResizeType.CenterCrop(
    canvasColor = null,      // null = transparent, 0xFF… = solid fill
    blurRadius = 40,         // blur radius for background fill
    originalSize = IntegerSize(4000, 3000),
    scaleFactor = 1.05f,     // slight overscale before crop
    position = Position.Center
)
```

```kotlin
// Fit image inside canvas with letterboxing/pillarboxing
val fit = ResizeType.Fit(
    canvasColor = 0xFFFFFFFF.toInt(),
    blurRadius = 0,
    position = Position.Center
)
```

```kotlin
// Preserve original size during crop operations
val withOriginal = centerCrop.withOriginalSizeIfCrop(IntegerSize(4000, 3000))
```

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

### Implementations of Image Filters

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Demonstrates various implementations of the `Filter` interface for different image manipulation tasks. Each filter has a specific `Value` type and `isVisible` property.

```kotlin
class SepiaFilterImpl : Filter.Sepia {
    override val value: Unit = Unit
    override val isVisible: Boolean = true
}
```

```kotlin
class SaturationFilterImpl(saturation: Float = 1.0f) : Filter.Saturation {
    override val value: Float = saturation
    override val isVisible: Boolean = true
}
```

```kotlin
class GaussianBlurFilterImpl : Filter.GaussianBlur {
    override val value: Triple<Float, Float, BlurEdgeMode> = 
        Triple(10f, 2.0f, BlurEdgeMode.Clamp)
    override val isVisible: Boolean = true
}
```

```kotlin
class ClaheFilterImpl : Filter.Clahe {
    override val value: Triple<Float, Float, Float> = 
        Triple(3.0f, 8f, 8f) // clipLimit, gridW, gridH
    override val isVisible: Boolean = true
}
```

```kotlin
class GlitchFilterImpl : Filter.EnhancedGlitch {
    override val value: GlitchParams = GlitchParams(
        channelsShiftX = -0.08f,
        channelsShiftY = -0.08f,
        corruptionSize = 0.01f,
        corruptionCount = 60,
        corruptionShiftX = -0.05f,
        corruptionShiftY = 0f
    )
    override val isVisible: Boolean = true
}
```

```kotlin
class ToneCurvesFilterImpl : Filter.ToneCurves {
    override val value: ToneCurvesParams = ToneCurvesParams.Default
    override val isVisible: Boolean = true
}
```

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

### Stage Changes for Commit

Source: https://github.com/t8rin/imagetoolbox/wiki/Contributing-Guidelines

Add modified files to the staging area. Use `git add .` to add all changes or `git add <file name>` to add specific files.

```bash
# To add all new files to branch Branch_Name  
git add .  

# To add only a few files to Branch_Name
git add <file name>
```

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

### ImageScaler Interface

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

The ImageScaler interface provides functionality to resize images with fine-grained control over algorithms and color spaces. It supports explicit resizing, flexible resizing that maintains aspect ratio, and center-cropping.

```APIDOC
## ImageScaler - Resize Images

### Description
Scales images to exact or adaptive dimensions using a wide range of resampling algorithms and color spaces. Supports explicit dimensions, flexible fitting, and center-cropping.

### Methods
- `scaleImage(image: Bitmap, width: Int, height: Int, resizeType: ResizeType, imageScaleMode: ImageScaleMode): Bitmap`
- `scaleUntilCanShow(bitmap: Bitmap): Bitmap?`

### Parameters
#### `ResizeType` Enum
- `Explicit(width: Int, height: Int)`: Resizes to exact dimensions.
- `Flexible(resizeAnchor: ResizeAnchor)`: Resizes while maintaining aspect ratio to fit within bounds.
- `CenterCrop(canvasColor: Int, blurRadius: Int, scaleFactor: Float, position: Position)`: Crops the image to a square and fills the background.

#### `ImageScaleMode` Enum
- `Lanczos3(scaleColorSpace: ScaleColorSpace)`: Uses Lanczos3 resampling algorithm.

### Usage Example
```kotlin
suspend fun resizeImage(
    imageScaler: ImageScaler<Bitmap>,
    bitmap: Bitmap
): Bitmap {
    // Explicit resize to 1920×1080 using Lanczos3 in Oklab color space
    val resized = imageScaler.scaleImage(
        image = bitmap,
        width = 1920,
        height = 1080,
        resizeType = ResizeType.Explicit,
        imageScaleMode = ImageScaleMode.Lanczos3(
            scaleColorSpace = ScaleColorSpace.OklabSRGB
        )
    )

    // Flexible resize — keeps aspect ratio, fits within given bounds
    val flexible = imageScaler.scaleImage(
        image = bitmap,
        width = 800,
        height = 600,
        resizeType = ResizeType.Flexible(resizeAnchor = ResizeAnchor.Default)
    )

    // Center-crop with blurred background fill
    val cropped = imageScaler.scaleImage(
        image = bitmap,
        width = 1080,
        height = 1080,
        resizeType = ResizeType.CenterCrop(
            canvasColor = 0xFF000000.toInt(),
            blurRadius = 35,
            scaleFactor = 1f,
            position = Position.Center
        )
    )

    // Scale down until the image can be displayed in memory safely
    return imageScaler.scaleUntilCanShow(bitmap) ?: bitmap
}
```
```

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

### Apply Filters to Bitmap

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

A utility function to apply a list of filters to a bitmap using a `FilterProvider`. Requires a `FilterProvider` and a list of `Filter` objects.

```kotlin
fun applyFilters(
    filterProvider: FilterProvider<Bitmap>,
    filters: List<Filter<*>>
): List<Transformation<Bitmap>> {
    return filters.map { filterProvider.filterToTransformation(it) }
}
```

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

### ImageGetter Interface

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

The ImageGetter interface is used for decoding images from various sources like URIs or assets into a usable Bitmap format. It supports loading full-resolution images, thumbnails, and images with applied transformations.

```APIDOC
## ImageGetter - Load Images

### Description
Loads images from any URI or data source into a typed image representation (typically Bitmap). Supports synchronous and asynchronous loading, optional transformations at decode time, and size constraints.

### Methods
- `getImage(uri: String, originalSize: Boolean, onFailure: (Throwable) -> Unit): ImageData<Bitmap>?`
- `getImage(data: String, size: Int): Bitmap?`
- `getImageWithTransformations(uri: String, transformations: List<Transformation<Bitmap>>, originalSize: Boolean): ImageData<Bitmap>?`

### Usage Example
```kotlin
// Injected via Hilt into any component
class MyComponent @AssistedInject constructor(
    private val imageGetter: ImageGetter<Bitmap>
) {
    // Load full-resolution image with metadata
    suspend fun loadImage(uri: String): ImageData<Bitmap>? {
        return imageGetter.getImage(
            uri = uri,
            originalSize = true,
            onFailure = { throwable -> Log.e("IMG", "Load failed", throwable) }
        )
        // Returns ImageData<Bitmap> containing:
        //   .image     -> Bitmap
        //   .imageInfo -> ImageInfo (width, height, format, quality, …)
        //   .metadata  -> Exif Metadata?
    }

    // Load a thumbnail (down-sampled to fit within 512 px)
    suspend fun loadThumbnail(uri: String): Bitmap? {
        return imageGetter.getImage(data = uri, size = 512)
    }

    // Load with applied filter transformations
    suspend fun loadWithFilters(
        uri: String,
        filters: List<Transformation<Bitmap>>
    ): ImageData<Bitmap>? {
        return imageGetter.getImageWithTransformations(
            uri = uri,
            transformations = filters,
            originalSize = false
        )
    }
}
```
```

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

### Configure Drawing Modes and Path Modes

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Select active brush tool types using DrawMode and geometric or freehand styles with DrawPathMode. DrawLineStyle can be used to decorate stroke rendering.

```kotlin
// Available DrawMode types
val pen = DrawMode.Pen
val neon = DrawMode.Neon
val highlighter = DrawMode.Highlighter
val privacyBlur = DrawMode.PathEffect.PrivacyBlur(blurRadius = 25)
val pixelation = DrawMode.PathEffect.Pixelation(pixelSize = 40f)
val filterBrush = DrawMode.PathEffect.Custom(filter = saturationFilter)
val textMode = DrawMode.Text(
    text = "© 2024",
    isRepeated = true,
    repeatingInterval = Pt(30f)
)
val imageBrush = DrawMode.Image(
    imageData = "content://media/images/stamp.png",
    repeatingInterval = Pt(50f)
)
val spotHeal = DrawMode.SpotHeal(mode = SpotHealMode.OpenCV)
val warp = DrawMode.Warp(warpMode = WarpMode.MOVE, strength = 0.3f, hardness = 0.6f)

// DrawPathMode selects path geometry
val freeDraw = DrawPathMode.Free
val line = DrawPathMode.Line
val arrow = DrawPathMode.PointingArrow(sizeScale = 3f, angle = 150f)
val rect = DrawPathMode.OutlinedRect(
    rotationDegrees = 45,
    cornerRadius = 12f,
    fillColor = ColorModel(0x4400FF00) // semi-transparent green fill
)
val star = DrawPathMode.OutlinedStar(
    vertices = 5,
    innerRadiusRatio = 0.45f,
    fillColor = null // outline only
)
val floodFill = DrawPathMode.FloodFill(tolerance = 0.15f)
val spray = DrawPathMode.Spray(density = 80, pixelSize = 2f, isSquareShaped = false)

// DrawLineStyle decorates stroke rendering
val dashed = DrawLineStyle.Dashed(size = 10.pt, gap = 20.pt)
val zigzag = DrawLineStyle.ZigZag(heightRatio = 4f)
val dotDashed = DrawLineStyle.DotDashed
```

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

### SettingsInteractor: Modifying App Settings

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Shows how to modify persistent app settings using the SettingsInteractor. Ensure the interactor is properly initialized and that DataStore is available for persistence.

```kotlin
suspend fun configureApp(interactor: SettingsInteractor) {
    interactor.setNightMode(NightMode.Dark)
    interactor.toggleAmoledMode()
    interactor.setPresets(listOf(25, 50, 75, 100))
    interactor.setSaveFolderUri("/storage/emulated/0/ImageToolbox")
    interactor.setFilenamePrefix("edited_")
    interactor.toggleAddSequenceNumber()
    interactor.setBorderWidth(2f)
    interactor.setDefaultImageScaleMode(ImageScaleMode.Lanczos3())
    interactor.setDefaultImageFormat(ImageFormat.Png.Lossless)
    interactor.toggleDynamicColors()
    interactor.setColorTuple("FF6200EE*FF03DAC5*FFFFFFFF*FF000000")
}
```

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

### Save and Manage Files with FileController

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Use FileController to save processed images and arbitrary bytes to the Android file system, read cache, manage output directories, and copy EXIF metadata. Ensure proper error handling for permission issues and exceptions.

```kotlin
suspend fun saveProcessedImage(
    fileController: FileController,
    bitmap: Bitmap,
    imageInfo: ImageInfo,
    compressor: ImageCompressor<Bitmap>
) {
    // Encode bitmap
    val bytes = compressor.compressAndTransform(bitmap, imageInfo)

    // Build a save target
    val saveTarget = ImageSaveTarget<ExifInterface>(
        imageInfo = imageInfo,
        originalUri = "content://media/external/images/1234",
        sequenceNumber = 1,
        data = bytes
    )

    // Save with EXIF preservation
    val result: SaveResult = fileController.save(
        saveTarget = saveTarget,
        keepOriginalMetadata = true,
        oneTimeSaveLocationUri = null   // null → use app default folder
    )

    when (result) {
        is SaveResult.Success -> println("Saved to ${result.savingPath}")
        is SaveResult.Error.MissingPermissions -> println("Grant storage permission")
        is SaveResult.Error.Exception -> println("Error: ${result.throwable.message}")
        is SaveResult.Skipped -> println("Skipped (duplicate)")
    }

    // Read raw bytes back
    val raw: ByteArray = fileController.readBytes("content://…/saved.avif")

    // Cache management
    val cacheBytes: Long = fileController.getCacheSize()
    fileController.clearCache { freed -> println("Freed ${freed / 1024} KB") }
}
```

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

### Encode Images to Byte Arrays with ImageCompressor

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Use ImageCompressor to encode Bitmaps into various image formats like AVIF and JXL. Supports lossy and lossless compression with configurable quality and effort levels. Can also estimate output file size.

```kotlin
suspend fun encodeImage(
    compressor: ImageCompressor<Bitmap>,
    bitmap: Bitmap
) {
    // Simple encode to AVIF lossy at quality 80, effort 4
    val avifBytes: ByteArray = compressor.compress(
        image = bitmap,
        imageFormat = ImageFormat.Avif.Lossy,
        quality = Quality.Avif(qualityValue = 80, effort = 4)
    )

    // Full pipeline: resize + rotate + encode to JXL lossless
    val info = ImageInfo(
        width = 2048,
        height = 1536,
        imageFormat = ImageFormat.Jxl.Lossless,
        quality = Quality.Jxl(qualityValue = 95, effort = 7, channels = Quality.Channels.RGBA),
        resizeType = ResizeType.Explicit,
        rotationDegrees = 90f,
        isFlipped = false,
        imageScaleMode = ImageScaleMode.Bilinear()
    )
    val jxlBytes: ByteArray = compressor.compressAndTransform(
        image = bitmap,
        imageInfo = info,
        applyImageTransformations = true
    )

    // Estimate output file size without writing to disk
    val estimatedBytes: Long = compressor.calculateImageSize(bitmap, info)
    println("Estimated size: ${estimatedBytes / 1024} KB")
}
```

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

### PdfManager Operations

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Provides a comprehensive set of operations for manipulating PDF files, including creation, extraction, merging, rotation, protection, compression, watermarking, OCR, and metadata editing.

```APIDOC
## createPdf

### Description
Converts a list of image URIs into a single PDF file.

### Method
`createPdf`

### Parameters
- `imageUris` (List<String>) - Required - List of URIs pointing to image files.
- `params` (PdfCreationParams) - Optional - Parameters for PDF creation, such as quality.

### Request Example
```kotlin
pdfManager.createPdf(
    imageUris = listOf("content://uri1.jpg", "content://uri2.png"),
    params = PdfCreationParams(quality = 90)
)
```

## extractPages

### Description
Extracts all pages from a PDF file as individual image files.

### Method
`extractPages`

### Parameters
- `uri` (String) - Required - URI of the PDF file.
- `params` (PdfExtractPagesParams) - Optional - Parameters for page extraction, specifying which pages to extract (null for all).

### Response
- `action` (ExtractPagesAction) - A flow emitting actions, including `Complete` with the result URI or `Page` with individual page URIs.

### Request Example
```kotlin
pdfManager.extractPages(
    uri = pdfUri,
    params = PdfExtractPagesParams(pages = null) // null = all pages
).collect { action ->
    when (action) {
        is ExtractPagesAction.Complete -> println("Done: ${action.resultUri}")
        is ExtractPagesAction.Page -> println("Page ${action.pageIndex}: ${action.uri}")
    }
}
```

## mergePdfs

### Description
Merges multiple PDF files into a single PDF document.

### Method
`mergePdfs`

### Parameters
- `uris` (List<String>) - Required - List of URIs pointing to the PDF files to merge.

### Request Example
```kotlin
pdfManager.mergePdfs(
    uris = listOf("content://doc1.pdf", "content://doc2.pdf")
)
```

## rotatePdf

### Description
Rotates specific pages of a PDF file by a given degree.

### Method
`rotatePdf`

### Parameters
- `uri` (String) - Required - URI of the PDF file.
- `rotations` (List<Int>) - Required - A list of rotation angles (0, 90, 180, 270 degrees), one for each page.

### Request Example
```kotlin
pdfManager.rotatePdf(
    uri = pdfUri,
    rotations = listOf(0, 90, 0, 270) // one angle per page
)
```

## protectPdf

### Description
Applies password protection to a PDF file.

### Method
`protectPdf`

### Parameters
- `uri` (String) - Required - URI of the PDF file.
- `password` (String) - Required - The password to protect the PDF with.

### Request Example
```kotlin
pdfManager.protectPdf(uri = pdfUri, password = "s3cr3t")
```

## compressPdf

### Description
Compresses a PDF file to reduce its size.

### Method
`compressPdf`

### Parameters
- `uri` (String) - Required - URI of the PDF file.
- `quality` (Float) - Optional - The compression quality, ranging from 0.0 to 1.0.

### Request Example
```kotlin
pdfManager.compressPdf(uri = pdfUri, quality = 0.7f)
```

## addWatermark

### Description
Adds a watermark to a PDF file.

### Method
`addWatermark`

### Parameters
- `uri` (String) - Required - URI of the PDF file.
- `params` (PdfWatermarkParams) - Required - Parameters for the watermark, such as text, opacity, and position.

### Request Example
```kotlin
pdfManager.addWatermark(
    uri = pdfUri,
    params = PdfWatermarkParams(/* text, opacity, position, … */)
)
```

## createSearchablePdf

### Description
Creates a searchable PDF from image pages with recognized text.

### Method
`createSearchablePdf`

### Parameters
- `pages` (List<SearchablePdfPage>) - Required - A list of pages, each containing an image URI and recognized text.

### Request Example
```kotlin
pdfManager.createSearchablePdf(
    pages = listOf(
        SearchablePdfPage(imageUri = "content://scan.jpg", recognizedText = "Hello World")
    )
)
```

## getPdfMetadata

### Description
Retrieves the metadata of a PDF file.

### Method
`getPdfMetadata`

### Parameters
- `uri` (String) - Required - URI of the PDF file.

### Response
- `meta` (PdfMetadata) - The metadata object of the PDF.

### Request Example
```kotlin
pdfManager.getPdfMetadata(uri = pdfUri)
```

## changePdfMetadata

### Description
Updates the metadata of a PDF file.

### Method
`changePdfMetadata`

### Parameters
- `uri` (String) - Required - URI of the PDF file.
- `metadata` (PdfMetadata) - Required - The updated metadata object.

### Request Example
```kotlin
pdfManager.changePdfMetadata(
    uri = pdfUri,
    metadata = meta.copy(author = "T8RIN", title = "My Document")
)
```
```

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

### HashingType

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Provides support for various hashing algorithms, including registration of custom providers and computation of file checksums.

```APIDOC
## registerSecurityMessageDigests

### Description
Registers custom security message digest providers.

### Method
`registerSecurityMessageDigests`

### Parameters
- `algorithms` (List<String>) - Required - A list of algorithm names to register.

### Request Example
```kotlin
HashingType.registerSecurityMessageDigests(
    Security.getAlgorithms("MessageDigest").toList()
)
```

## MD5

### Description
Represents the MD5 hashing algorithm.

### Usage
`val md5 = HashingType.MD5`

## SHA_256

### Description
Represents the SHA-256 hashing algorithm.

### Usage
`val sha256 = HashingType.SHA_256`

## entries

### Description
Retrieves a list of all available HashingType entries.

### Method
`entries`

### Response
- `all` (List<HashingType>) - A list of all available hashing algorithms.

### Request Example
```kotlin
val all: List<HashingType> = HashingType.entries
```

## fromString

### Description
Looks up a HashingType by its digest string.

### Method
`fromString`

### Parameters
- `digest` (String) - Required - The string representation of the digest algorithm (e.g., "SHA-512").

### Response
- `found` (HashingType?) - The found HashingType or null if not found.

### Request Example
```kotlin
val found: HashingType? = HashingType.fromString("SHA-512")
```
```

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

### SettingsInteractor Operations

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Provides functions to observe and modify application-wide settings, which are persisted using DataStore.

```APIDOC
## getSettingsState

### Description
Observes the current application settings.

### Method
`getSettingsState`

### Response
- `state` (Flow<SettingsState>) - A flow emitting the current `SettingsState`.

### Request Example
```kotlin
settingsProvider.getSettingsState().collect { state: SettingsState ->
    println("Theme: ${state.nightMode}")
    println("Dynamic colors: ${state.isDynamicColors}")
    println("AMOLED: ${state.isAmoledMode}")
    println("Font: ${state.font}")
    println("Default format: ${state.defaultImageFormat}")
    println("Default scale: ${state.defaultImageScaleMode}")
    println("Save folder: ${state.saveFolderUri}")
    println("Presets: ${state.presets}")
}
```

## setNightMode

### Description
Sets the application's night mode.

### Method
`setNightMode`

### Parameters
- `nightMode` (NightMode) - Required - The desired night mode (e.g., `NightMode.Dark`).

## toggleAmoledMode

### Description
Toggles the AMOLED mode setting.

### Method
`toggleAmoledMode`

## setPresets

### Description
Sets the list of image presets.

### Method
`setPresets`

### Parameters
- `presets` (List<Int>) - Required - A list of integer values representing presets.

## setSaveFolderUri

### Description
Sets the default folder URI for saving images.

### Method
`setSaveFolderUri`

### Parameters
- `uri` (String) - Required - The URI of the save folder.

## setFilenamePrefix

### Description
Sets the prefix for generated filenames.

### Method
`setFilenamePrefix`

### Parameters
- `prefix` (String) - Required - The filename prefix.

## toggleAddSequenceNumber

### Description
Toggles the addition of sequence numbers to filenames.

### Method
`toggleAddSequenceNumber`

## setBorderWidth

### Description
Sets the border width for images.

### Method
`setBorderWidth`

### Parameters
- `width` (Float) - Required - The border width.

## setDefaultImageScaleMode

### Description
Sets the default image scaling mode.

### Method
`setDefaultImageScaleMode`

### Parameters
- `scaleMode` (ImageScaleMode) - Required - The desired image scale mode.

## setDefaultImageFormat

### Description
Sets the default image format.

### Method
`setDefaultImageFormat`

### Parameters
- `format` (ImageFormat) - Required - The desired image format.

## toggleDynamicColors

### Description
Toggles the dynamic color feature.

### Method
`toggleDynamicColors`

## setColorTuple

### Description
Sets a color tuple for application theming.

### Method
`setColorTuple`

### Parameters
- `colorTuple` (String) - Required - A string representing the color tuple.

### Request Example
```kotlin
interactor.setNightMode(NightMode.Dark)
interactor.toggleAmoledMode()
interactor.setPresets(listOf(25, 50, 75, 100))
interactor.setSaveFolderUri("/storage/emulated/0/ImageToolbox")
interactor.setFilenamePrefix("edited_")
interactor.toggleAddSequenceNumber()
interactor.setBorderWidth(2f)
interactor.setDefaultImageScaleMode(ImageScaleMode.Lanczos3())
interactor.setDefaultImageFormat(ImageFormat.Png.Lossless)
interactor.toggleDynamicColors()
interactor.setColorTuple("FF6200EE*FF03DAC5*FFFFFFFF*FF000000")
```
```

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

### Apply Drawing Paths to Images

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Use ImageDrawApplier to render PathPaint strokes onto an image URI or an existing bitmap. Supports alpha-erasing and background-shader revealing.

```kotlin
suspend fun applyDrawing(
    drawApplier: ImageDrawApplier<Bitmap, Path, Color>,
    pathPaints: List<PathPaint<Path, Color>>,
    imageUri: String
): Bitmap? {
    // Paint strokes on top of an existing image
    return drawApplier.applyDrawToImage(
        drawBehavior = DrawBehavior.Image(imageUri),
        pathPaints = pathPaints,
        imageUri = imageUri
    )
    // Each PathPaint carries:
    //   .path         -> Path geometry
    //   .strokeWidth  -> Pt (device-independent)
    //   .brushSoftness -> Pt (feathering)
    //   .drawColor    -> Color
    //   .isErasing    -> Boolean
    //   .drawMode     -> DrawMode (Pen, Neon, etc.)
    //   .drawPathMode -> DrawPathMode (Free, Rect, Star, etc.)
    //   .drawLineStyle -> DrawLineStyle (None, Dashed, ZigZag, etc.)
}

suspend fun eraseBackground(
    drawApplier: ImageDrawApplier<Bitmap, Path, Color>,
    pathPaints: List<PathPaint<Path, Color>>,
    image: Bitmap,
    shaderSourceUri: String
): Bitmap? {
    // Erase pixels along paths, revealing the background shader
    return drawApplier.applyEraseToImage(
        pathPaints = pathPaints,
        image = image,
        shaderSourceUri = shaderSourceUri
    )
}
```

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

### Apply Transformations with ImageTransformer

Source: https://context7.com/t8rin/imagetoolbox/llms.txt

Utilize ImageTransformer to apply a series of transformations, including filters, rotation, and flipping, to a Bitmap. Transformations can be applied at original resolution or a specified output size.

```kotlin
suspend fun transformImage(
    transformer: ImageTransformer<Bitmap>,
    filterProvider: FilterProvider<Bitmap>,
    bitmap: Bitmap
): Bitmap? {
    // Build filter chain: Saturation → GaussianBlur → Vignette
    val saturationFilter: Filter.Saturation = /* inject or create */ ...
    val blurFilter: Filter.GaussianBlur = /* inject or create */ ...
    val vignetteFilter: Filter.Vignette = /* inject or create */ ...

    val transformations = listOf(
        filterProvider.filterToTransformation(saturationFilter),
        filterProvider.filterToTransformation(blurFilter),
        filterProvider.filterToTransformation(vignetteFilter),
    )

    // Apply at original image resolution
    val filtered: Bitmap? = transformer.transform(
        image = bitmap,
        transformations = transformations,
        originalSize = true
    )

    // Apply at a fixed output size
    val filteredSmall: Bitmap? = transformer.transform(
        image = bitmap,
        transformations = transformations,
        size = IntegerSize(1024, 768)
    )

    // Rotate 45 degrees
    val rotated: Bitmap = transformer.rotate(bitmap, degrees = 45f)

    // Flip horizontally
    val flipped: Bitmap = transformer.flip(bitmap, isFlipped = true)

    // Apply a size preset (e.g. 50% scale)
    val currentInfo = ImageInfo(width = 4000, height = 3000)
    val newInfo: ImageInfo = transformer.applyPresetBy(
        image = bitmap,
        preset = Preset.Percentage(50),
        currentInfo = currentInfo
    )
    // newInfo.width == 2000, newInfo.height == 1500
    return filtered
}
```

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

### Push Changes to Remote Repository

Source: https://github.com/t8rin/imagetoolbox/wiki/Contributing-Guidelines

Push the committed changes from your local branch to your remote repository.

```bash
git push origin branch_name
```

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

### Commit Changes

Source: https://github.com/t8rin/imagetoolbox/wiki/Contributing-Guidelines

Commit your staged changes with a descriptive message. A pull request should ideally contain only one commit.

```bash
git commit -m "message"  
```
Tokens:
Raw