DOCSEARCHbyAlgolia
Submit Docs

ZoomImage Documentation

repository·main·Indexed 20 days ago

https://github.com/panpf/zoomimage

A high-performance image viewing library supporting gesture zooming, rotation, and subsampling for large images. It is designed for Compose Multiplatform (Android, iOS, Desktop, Web) and traditional Android Views, with integrations for image loaders including Sketch, Coil, Glide, and Picasso.

Tokens
32.4K
Snippets
74
Records
119
Agent score
71%

What's inside ZoomImage

  1. Overview of ZoomImage

    main

    ZoomImage is a gesture-based image zooming and viewing library designed for Compose Multiplatform and Android View. It provides advanced features for handling large images and interactive viewing across multiple platforms.

    Key Features

    • Multiplatform Support: Works on Android, iOS, macOS, Windows, Linux, and Web.
    • Gestures: Supports double-tap zoom, pinch-to-zoom, single-finger zoom, mouse wheel zoom, keyboard zoom, single-finger drag, inertial scrolling, and keyboard dragging.
    • Advanced Viewing: Includes image rotation (0°, 90°, 180°, 270°, 360°), ability to locate and center on specific image coordinates, and rubber-band damping effects when exceeding zoom limits.
    • Performance: Supports subsampling for ultra-large images to prevent Out-Of-Memory (OOM) errors, featuring smooth animations and clarity gradients.
    • UI Enhancements: Supports horizontal and vertical scrollbars and a 'Read Mode' that automatically fills the screen with long images for immediate viewing.
    • Exif Support: Automatically handles Exif Orientation information to rotate images correctly.
    • Image Loader Integration: Built-in support for Sketch, Coil, Glide, and Picasso.

  2. Explore ZoomImage documentation and components

    main

    The ZoomImage documentation covers various features for image manipulation and viewing. Key capabilities include:

    • Transformations: Scaling, Offsetting (moving), and Rotating images.
    • Navigation: Locating specific coordinates in an image and using Scroll Bars (horizontal/vertical).
    • Advanced Viewing: Using Read Mode for long images and Subsampling to prevent Out-of-Memory (OOM) errors when displaying large images.
    • State Management: Keeping transforms consistent when switching images.
    • Interactions: Handling click events and using Modifier.zoom().

    Depending on your platform and image loading library, you can use different implementations such as ZoomImage (Compose), ZoomImageView (View), or integrations with Coil, Glide, Sketch, and Picasso.

  3. Choose the right ZoomImage component

    main

    ZoomImage provides different components depending on your target platform (Compose Multiplatform, Android Compose, or Android View) and your preferred image loading library.

    Compose Multiplatform

    • SketchZoomAsyncImage (Recommended): Integrates with [Sketch]. Supports network images and subsampling.
    • CoilZoomAsyncImage: Integrates with [Coil]. Supports network images and subsampling.
    • ZoomImage: Basic component. Does not integrate an image loader and does not support network images out of the box. You must manually call subsampling.setImageResource() to enable subsampling.

    Android Compose (Only)

    • GlideZoomAsyncImage: Integrates with [Glide]. Supports network images and subsampling.

    Android View

    • SketchZoomImageView (Recommended): Integrates with [Sketch]. Supports network images and subsampling.
    • CoilZoomImageView: Integrates with [Coil]. Supports network images and subsampling.
    • GlideZoomImageView: Integrates with [Glide]. Supports network images and subsampling.
    • PicassoZoomImageView: Integrates with [Picasso]. Supports network images and subsampling. Note: Use the component's specialized APIs to listen for load results to support subsampling; do not use the official Picasso API directly for loading.
    • ZoomImageView: Basic component. Does not integrate an image loader. Requires manual calls to subsampling.setImageResource() for subsampling.

    Important Notes:

    • Components with integrated loaders handle network images and subsampling automatically.
    • Components without integrated loaders only display local images and require an additional call to setSubsamplingImage() (Compose) or setSubsamplingImage() (View) to enable subsampling functionality.
    • Ensure you import the correct dependencies for your chosen component as specified in the README.

  4. Choose the appropriate ZoomImage component

    main

    ZoomImage provides different components depending on your target platform (Compose Multiplatform vs. Android-only) and your preferred image loading library.

    Compose Multiplatform

    • SketchZoomAsyncImage (Recommended): Integrates with Sketch. Supports network images and sub-sampling automatically.
    • CoilZoomAsyncImage: Integrates with Coil. Supports network images and sub-sampling automatically.
    • ZoomImage: The base component. Does not integrate an image loader. It only supports local images and requires manual calls to subsampling.setImageResource() to enable sub-sampling.

    Android Compose (Android-only)

    • GlideZoomAsyncImage: Integrates with Glide. Supports network images and sub-sampling automatically.

    Android View

    • SketchZoomImageView (Recommended): Integrates with Sketch.
    • CoilZoomImageView: Integrates with Coil.
    • GlideZoomImageView: Integrates with Glide.
    • PicassoZoomImageView: Integrates with Picasso. Note: Use the component's dedicated APIs to load images to ensure sub-sampling works correctly; do not use standard Picasso APIs directly.
    • ZoomImageView: The base component. Does not integrate an image loader. Requires manual calls to subsampling.setImageResource() for sub-sampling.

  5. Multiplatform Support (iOS, JS, WasmJs)

    main

    Version 1.1.0-alpha01 introduced multiplatform support for JS, WasmJs, and iOS.

    Important Breaking Changes for Multiplatform:

    • Non-Android platforms now use Skia for image decoding.
    • ImageSource.fromResource() on desktop platforms has been renamed to fromKotlinResource().
    • ImageSource.fromFile(File) is now an extension function exclusive to the JVM platform.
    • ImageSource now uses okio.Source instead of InputStream.

  6. Choose the right ZoomImage component for your project

    main

    ZoomImage provides several implementations based on your UI framework and image loading library:

    Jetpack Compose (Multiplatform)

    • ZoomImage: The core Compose component.
    • CoilZoomAsyncImage: Integration with Coil.
    • GlideZoomAsyncImage: Integration with Glide.
    • SketchZoomAsyncImage: Integration with Sketch.

    Android Views

    • ZoomImageView: The core View-based component.
    • CoilZoomImageView: Integration with Coil.
    • GlideZoomImageView: Integration with Glide.
    • PicassoZoomImageView: Integration with Picasso.
    • SketchZoomImageView: Integration with Sketch.

  7. Configure ReadMode parameters

    main

    The ReadMode class controls how the reading experience is triggered and how it behaves. It accepts two primary parameters:

    1. sizeType: Int: Determines which image orientations can trigger Read Mode.

      • ReadMode.SIZE_TYPE_HORIZONTAL
      • ReadMode.SIZE_TYPE_VERTICAL
      • Default: Supports both.

    2. decider: ReadMode.Decider: A logic component that decides whether Read Mode should be applied based on the relationship between the contentSize and the containerSize.

      • Default: ReadMode.Decider.Default (which uses ReadMode.LongImageDecider to target only long images).

    You can implement the ReadMode.Decider interface to define your own custom rules for when Read Mode should activate.

  8. How Zoom and Subsampling work in Compose and Views

    main

    ZoomImage separates scaling (zoom) and subsampling (tiling/detail loading) into distinct APIs. Depending on your UI framework, you use different classes to access these capabilities:

    Jetpack Compose

    Use ZoomableState and SubsamplingState obtained from a ZoomState.

    Android Views

    Use ZoomableEngine and SubsamplingEngine obtained from a SketchZoomImageView.

    Note on State: In Compose, properties are wrapped in State for direct reading in Composables. In Views, properties are wrapped in StateFlow and require collection to listen for changes.

    // Compose usage
val zoomState: ZoomState by rememberSketchZoomState()
SketchZoomAsyncImage(
    uri = "https://sample.com/sample.jpeg",
    contentDescription = "view image",
    modifier = Modifier.fillMaxSize(),
    zoomState = zoomState,
)
val zoomable: ZoomableState = zoomState.zoomable
val subsampling: SubsamplingState = zoomState.subsampling

// View usage
val sketchZoomImageView = SketchZoomImageView(context)
val zoomable: ZoomableEngine = sketchZoomImageView.zoomable
val subsampling: SubsamplingEngine = sketchZoomImageView.subsampling

  9. Listen to property changes in Compose and View

    main

    To react to changes in rotation or zoom state:

    • Compose: Properties are wrapped in State. You can read them directly within a Composable function to trigger recomposition.
    • View: Properties are wrapped in StateFlow. You must use the collect function (or collectAsState in Compose interop) to listen for updates.

  10. How ZoomImage handles transformation state resets

    main

    ZoomImage manages how the transformation state (zoom, rotation, etc.) is preserved or reset when certain properties change.

    By default, ZoomImage will directly reset the transformation state if any of the following properties are modified:

    • rotation
    • contentScale
    • alignment
    • readMode
    • scalesCalculator
    • limitOffsetWithinBaseVisibleRect
    • containerWhitespaceMultiple
    • containerWhitespace

    However, it handles containerSize and contentSize differently to provide a smoother user experience.

  11. Maintain transformation state when containerSize changes

    main
    When only the containerSize property changes, ZoomImage attempts to restore the current transformation state based on the new size. It ensures that the center point currently visible to the user remains in the center of the screen. This allows the component to adapt to window resizing (e.g., on desktop platforms) while keeping the user's focus point stable.

  12. How ZoomImage adapts to containerSize changes

    main

    When the containerSize property changes (e.g., resizing a window on desktop), ZoomImage does not reset the transformation state. Instead, it restores the transform state relative to the new container size.

    This ensures that the center point currently visible to the user remains in the center of the screen, allowing the visible range to adapt to the new window size without losing the user's current view position.