tessera

Tessera (Latin: "small tile piece") — A Compose Multiplatform tile-based high-resolution image viewer

Tessera is a memory-efficient image viewer for Compose Multiplatform. It uses tile-based rendering and platform-native decoders to handle images up to 108MP+ — keeping memory usage up to 95% lower than full-image loading.

• 108MP+ Support — Handles images up to 12000px+ on mobile devices with limited RAM
• Memory Efficient — Subsample decoding + tile-based rendering, only visible tiles in memory
• 1ms Tile Rendering — Skia-optimized tile extraction averages 1-2ms per tile
• Smooth Gestures — 60fps pinch-to-zoom, pan, and double-tap zoom
• Pager Ready — HorizontalPager integration with smart gesture routing (swipe vs pan)
• Compose Native — Built for Compose Multiplatform (not a View wrapper)
• LRU Tile Cache — Automatic eviction with configurable cache size (default: 150 tiles)
• Multiple Image Sources — Network URLs, local files, Android content URIs and resources
• EXIF Orientation — Automatic rotation/mirror correction for all 8 EXIF orientations
• Manual Rotation — User-controlled rotation via ImageRotation enum (None, Rotate90, Rotate180, Rotate270)
• ReadMode — Auto-detect tall/wide images with FitWidth/FitHeight content scaling
• Scroll Indicators — Minimap + scroll bars for zoomed-in navigation (auto-hide)
• Zero Core Dependencies — tessera-core has no external image library dependencies
• Optional Loaders — tessera-coil (KMP) and tessera-glide (Android) companion modules

Add dependencies to your build.gradle.kts:

// Core library (required)
implementation("io.github.bentleypark:tessera-core:<version>")

// Optional: Coil image loader (Android + iOS KMP)
implementation("io.github.bentleypark:tessera-coil:<version>")

// Optional: Glide image loader (Android only)
implementation("io.github.bentleypark:tessera-glide:<version>")

@Composable
fun MyScreen() {
    // Basic usage (built-in NetworkImageLoader)
    TesseraImage(
        imageUrl = "https://example.com/large-image.jpg",
        modifier = Modifier.fillMaxSize()
    )

    // With Coil loader
    val coilLoader = remember { CoilImageLoader(context) }
    TesseraImage(
        imageUrl = "https://example.com/large-image.jpg",
        modifier = Modifier.fillMaxSize(),
        imageLoader = coilLoader
    )

    // Android resource
    TesseraImage(
        imageResId = R.drawable.large_image,
        modifier = Modifier.fillMaxSize()
    )
}

// Kotlin — Basic (built-in IosImageLoader with NSURLSession)
fun MainViewController() = ComposeUIViewController {
    TesseraImage(
        imageUrl = "https://example.com/large-image.jpg",
        modifier = Modifier.fillMaxSize()
    )
}

// Kotlin — With Coil loader
fun MainViewController() = ComposeUIViewController {
    val coilLoader = remember { CoilImageLoader() }
    TesseraImage(
        imageUrl = "https://example.com/large-image.jpg",
        modifier = Modifier.fillMaxSize(),
        imageLoader = coilLoader
    )
}

// Swift — With Coil loader (via TesseraCoil framework)
import TesseraCoil

let coilLoader = CoilImageLoader.companion.create()
MainViewControllerKt.MainViewController(imageLoader: coilLoader)

fun main() = application {
    Window(title = "Tessera Desktop") {
        TesseraImage(
            imageUrl = "https://example.com/large-image.jpg",
            modifier = Modifier.fillMaxSize(),
            showScrollIndicators = true
        )
    }
}

Desktop Gestures:

@OptIn(ExperimentalComposeUiApi::class)
fun main() {
    CanvasBasedWindow(title = "Tessera Web", canvasElementId = "ComposeTarget") {
        TesseraImage(
            imageUrl = "https://example.com/large-image.jpg",
            modifier = Modifier.fillMaxSize()
        )
    }
}

Note: Web support is experimental (Kotlin/Wasm). Unlike Android/iOS/Desktop which use partial or subsampled decoding, the web decoder loads the entire image into memory (no browser partial decode API). Practical limit is ~30MP (2–4 GB JS heap). For larger images, consider server-side tile generation.

Benchmarked on iPhone 7 (A10 Fusion, 2GB RAM, iOS 15.8.5) — 5 runs each:

Benchmarks run on iPhone 7 (A10 Fusion, 2GB RAM, iOS 15.8.5), 5 runs each. All benchmarks use JPEG images. Android uses BitmapRegionDecoder (Tier 1 partial decode) — memory footprint scales with tile size, not image size.

JPEG provides the best performance across all platforms due to its block-based compression structure. PNG, WebP, and other formats are supported but may have higher memory overhead during decoding. GIF animation is not supported — only the first frame is displayed.

Large non-JPEG images (iOS / Desktop): Tessera logs a warning at initialization when a PNG or other non-JPEG image exceeds 30MP. Subsample APIs decode the full image internally before downscaling — a 30MP PNG requires ~120MB during decode before the ~30MB result is cached. For images over 30MP, JPEG is strongly recommended. Filter Logcat/console by tag Tessera to catch these warnings. A callback API (onWarning) may be added in a future release based on user demand.

tessera/
├── tessera-core/      # Core library (Android + iOS + Desktop + Web, zero external deps)
├── tessera-coil/      # Coil 3.x image loader (Android + iOS KMP)
├── tessera-glide/     # Glide 5.x image loader (Android only)
├── sample/            # Android sample app
├── sample-desktop/    # Desktop (JVM) sample app
├── sample-web/        # Web (Wasm) sample app
└── iosApp/            # iOS sample app (SwiftUI + Compose)

TesseraImage (Composable)           <- User-facing API
  |-- Gesture detection
  |-- Canvas tile rendering
  v
TesseraState                        <- State + LRU Cache
  |-- initializeDecoder() on background thread
  |-- applyInitResult() on main thread
  |-- decodeTile() / cacheTile() split for thread safety
  v
TileManager                         <- Grid Calculation
  |-- Zoom level (0-3)
  |-- Visible tile selection
  v
RegionDecoder (expect/actual)       <- Platform Decoding
  |-- Android: BitmapRegionDecoder (true region decoding)
  |-- iOS: CGImageSource subsample + Skia tile extraction
  |-- Desktop: ImageIO subsample cache + getSubimage extraction
  |-- Web: Skia Image.makeFromEncoded + Surface.drawImageRect

Three distinct decoding tiers exist across platforms:

Tier 1 — Partial Decode

• Android: BitmapRegionDecoder requests only the tile region from the decoder. Memory efficiency is highest with JPEG (DCT block structure); PNG and other formats may incur higher internal overhead depending on Android's codec implementation.

Tier 2 — Subsample + Tile Extraction (JPEG optimized)

• iOS: CGImageSource with kCGImageSourceSubsampleFactor decodes at 1/2, 1/4, or 1/8 resolution. Skia drawImageRect extracts tiles at ~1ms each. 108MP JPEG → ~6.7MP in memory (~21MB).
• Desktop: ImageIO with setSourceSubsampling decodes at reduced resolution. Cached BufferedImage serves tiles via getSubimage. Same memory profile as iOS.
• Note: Subsample is only effective for JPEG (DCT block skipping). For PNG and other formats, the decoder loads the full image internally before returning a scaled result — memory savings apply to the cached result only, not during decode. For PNG images over 30MP on iOS/Desktop, this internal full decode may cause OOM before the result is returned. Tessera logs a warning at initialization when a large non-JPEG image is detected.

Tier 3 — Full Decode + Tile Extraction

• Web: Browsers provide no partial image decode API. The entire image is decoded into memory via Image.makeFromEncoded, then tiles are extracted via Skia Surface.drawImageRect.

Web limitation: The 30MP practical limit is a fundamental browser constraint (2–4 GB JS heap), not a Tessera limitation. For images larger than 30MP on web, server-side tile generation is the recommended approach. Web support functions as a zoom viewer rather than a true tile-based viewer.

Android uses BitmapRegionDecoder (true partial decode), so no subsampling step is needed — memory stays at tile level (~0.25MB per 256×256 tile) regardless of image size.

Tessera supports HorizontalPager for image gallery browsing:

val pagerState = rememberPagerState { images.size }

HorizontalPager(state = pagerState) { page ->
    TesseraImage(
        imageUrl = images[page],
        modifier = Modifier.fillMaxSize(),
        enablePagerIntegration = true,  // Enable swipe between pages
        enableDismissGesture = true
    )
}

Gesture behavior with enablePagerIntegration = true:

For long images (webtoons, documents) or wide images (panoramas), use ContentScale to auto-fit:

// Auto-detect: tall → FitWidth, wide → FitHeight, normal → Fit
TesseraImage(
    imageUrl = "https://example.com/webtoon.jpg",
    contentScale = ContentScale.Auto
)

// Force fit to width (vertical scroll)
TesseraImage(
    imageUrl = "https://example.com/document.jpg",
    contentScale = ContentScale.FitWidth
)

# Android build + tests
./gradlew :tessera-core:testDebugUnitTest

# Desktop build + tests
./gradlew :tessera-core:compileKotlinDesktop
./gradlew :tessera-core:desktopTest

# Web (Wasm) build
./gradlew :tessera-core:compileKotlinWasmJs

# Build all modules
./gradlew :tessera-core:assembleDebug :tessera-coil:assembleDebug :tessera-glide:assembleDebug

# iOS framework
./gradlew :tessera-core:linkDebugFrameworkIosSimulatorArm64

# iOS framework with Coil
./gradlew :tessera-coil:linkDebugFrameworkIosSimulatorArm64

# Run sample apps
./gradlew :sample-desktop:run                          # Desktop
./gradlew :sample-web:wasmJsBrowserDevelopmentRun      # Web (localhost:8080)

# All platform tests
./gradlew :tessera-core:allTests

# Run all tests
./gradlew :tessera-core:testDebugUnitTest   # Android (Robolectric)
./gradlew :tessera-core:desktopTest          # Desktop (JVM)

• Android: API 28+ (Android 9)
• iOS: iOS 15+
• Desktop: JDK 21+ (macOS, Windows, Linux)
• Web: Modern browser with WebGL + WebAssembly support
• Kotlin: 2.3.0+
• Compose Multiplatform: 1.8.0+
• JDK: 21+

Contributions are welcome! See CONTRIBUTING.md for development setup, build commands, and guidelines.

Copyright 2026 bentleypark

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.