subsampling-scale-image-view
Android library (AAR). Highly configurable, easily extendable deep zoom view for displaying huge images without loss of detail. Perfect for photo galleries, maps, building plans etc.
Top Related Projects
Implementation of ImageView for Android that supports zooming, by various touch gestures.
An image loading and caching library for Android focused on smooth scrolling
A powerful image downloading and caching library for Android
Powerful and flexible library for loading, caching and displaying images on Android.
An Android library for managing images and the memory they use.
An Android transformation library providing a variety of image transformations for Glide.
Quick Overview
SubsamplingScaleImageView is an Android library that provides a custom ImageView for displaying large images with smooth zooming and panning. It efficiently handles very large images by loading and displaying them in tiles, allowing for high-performance viewing of images that would otherwise be too large to display on mobile devices.
Pros
- Efficient handling of large images through tiling and subsampling
- Smooth zooming and panning with gesture support
- Memory-efficient, suitable for mobile devices with limited resources
- Customizable with various display options and event listeners
Cons
- Limited to Android platform
- May require additional setup for certain image formats or sources
- Learning curve for advanced customization
- Potential performance issues with extremely large images or low-end devices
Code Examples
- Basic usage:
SubsamplingScaleImageView imageView = new SubsamplingScaleImageView(context);
imageView.setImage(ImageSource.asset("large_image.jpg"));
- Setting initial scale and center:
imageView.setImage(ImageSource.uri("/sdcard/large_image.jpg"));
imageView.setScaleAndCenter(1.0f, new PointF(1000, 1000));
- Adding a pin to the image:
imageView.setImage(ImageSource.resource(R.drawable.large_image));
imageView.setPinchToZoom(true);
imageView.setOnImageEventListener(new DefaultOnImageEventListener() {
@Override
public void onReady() {
imageView.setPinPosition(new PointF(1000, 1000));
}
});
Getting Started
To use SubsamplingScaleImageView in your Android project:
- Add the dependency to your app's
build.gradle
:
dependencies {
implementation 'com.davemorrissey.labs:subsampling-scale-image-view:3.10.0'
}
- Add the view to your layout XML:
<com.davemorrissey.labs.subscaleview.SubsamplingScaleImageView
android:id="@+id/imageView"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
- Set the image in your activity or fragment:
SubsamplingScaleImageView imageView = findViewById(R.id.imageView);
imageView.setImage(ImageSource.asset("large_image.jpg"));
Competitor Comparisons
Implementation of ImageView for Android that supports zooming, by various touch gestures.
Pros of PhotoView
- Simpler implementation and easier to integrate into existing projects
- Supports GIF animations and custom touch gestures
- More actively maintained with frequent updates and bug fixes
Cons of PhotoView
- Less efficient memory management for large images
- Limited support for tiling and subsampling of high-resolution images
- May experience performance issues with extremely large images
Code Comparison
PhotoView:
PhotoView photoView = findViewById(R.id.photo_view);
photoView.setImageResource(R.drawable.my_image);
photoView.setMaximumScale(10f);
SubsamplingScaleImageView:
SubsamplingScaleImageView imageView = findViewById(R.id.imageView);
imageView.setImage(ImageSource.resource(R.drawable.my_image));
imageView.setMaxScale(10f);
Both libraries offer similar basic functionality for image viewing and zooming. PhotoView is more straightforward to implement, while SubsamplingScaleImageView provides better performance for large images through tiling and subsampling techniques. The choice between the two depends on the specific requirements of your project, such as image sizes, memory constraints, and desired features.
An image loading and caching library for Android focused on smooth scrolling
Pros of Glide
- Broader functionality: Glide is a comprehensive image loading and caching library, handling various image sources and formats
- Memory efficiency: Implements automatic memory and disk caching
- Extensive customization: Offers a wide range of image transformations and loading options
Cons of Glide
- Larger library size: Glide includes many features, which can increase app size
- Learning curve: More complex API due to its extensive functionality
- Not specialized for large images: May not perform as well with very large images compared to SubsamplingScaleImageView
Code Comparison
SubsamplingScaleImageView:
SubsamplingScaleImageView imageView = new SubsamplingScaleImageView(context);
imageView.setImage(ImageSource.uri("/sdcard/image.jpg"));
Glide:
ImageView imageView = findViewById(R.id.imageView);
Glide.with(this).load("/sdcard/image.jpg").into(imageView);
SubsamplingScaleImageView is specifically designed for handling large images with efficient memory usage and smooth zooming. It excels at displaying high-resolution images without out-of-memory errors. Glide, on the other hand, is a more versatile image loading library that handles various image sources and offers extensive caching and transformation options. While Glide can handle large images, it may not provide the same level of specialized performance for very large, zoomable images as SubsamplingScaleImageView.
A powerful image downloading and caching library for Android
Pros of Picasso
- Comprehensive image loading and caching library with a wide range of features
- Supports multiple image sources (network, local storage, resources)
- Easy to use with a fluent API and minimal setup required
Cons of Picasso
- Limited support for large, high-resolution images
- Lacks advanced zooming and panning capabilities
- May not be ideal for displaying single, detailed images
Code Comparison
Picasso:
Picasso.get()
.load("https://example.com/image.jpg")
.into(imageView);
Subsampling Scale Image View:
SubsamplingScaleImageView imageView = new SubsamplingScaleImageView(context);
imageView.setImage(ImageSource.uri("https://example.com/image.jpg"));
Summary
Picasso is a versatile image loading library suitable for most general-purpose image loading tasks in Android applications. It excels in handling multiple image sources and provides efficient caching mechanisms.
Subsampling Scale Image View, on the other hand, is specifically designed for displaying large, high-resolution images with advanced zooming and panning capabilities. It's more suitable for applications that require detailed image viewing, such as photo galleries or map applications.
Choose Picasso for general image loading needs and Subsampling Scale Image View for applications requiring detailed image inspection and manipulation.
Powerful and flexible library for loading, caching and displaying images on Android.
Pros of Android-Universal-Image-Loader
- Supports a wider range of image loading scenarios, including network, local storage, and assets
- Offers more customization options for caching, display, and processing
- Provides a unified API for handling various image sources and types
Cons of Android-Universal-Image-Loader
- Less specialized for handling large, zoomable images
- May have higher memory usage for very large images
- Not optimized specifically for subsampling and tiling of large images
Code Comparison
Android-Universal-Image-Loader:
ImageLoader imageLoader = ImageLoader.getInstance();
DisplayImageOptions options = new DisplayImageOptions.Builder()
.cacheInMemory(true)
.cacheOnDisk(true)
.build();
imageLoader.displayImage(imageUri, imageView, options);
subsampling-scale-image-view:
SubsamplingScaleImageView imageView = new SubsamplingScaleImageView(context);
imageView.setImage(ImageSource.uri(imageUri));
The Android-Universal-Image-Loader code shows its flexibility in configuring image loading options, while the subsampling-scale-image-view code demonstrates its simplicity for handling large, zoomable images. The latter is more focused on efficiently displaying and interacting with high-resolution images, while the former provides a more general-purpose image loading solution.
An Android library for managing images and the memory they use.
Pros of Fresco
- Comprehensive image loading and caching library with support for multiple image formats
- Efficient memory management and automatic memory optimization
- Extensive customization options and support for image transformations
Cons of Fresco
- Larger library size and potential impact on app size
- Steeper learning curve due to more complex API and features
- May be overkill for simple image loading tasks
Code Comparison
Fresco:
SimpleDraweeView draweeView = findViewById(R.id.my_image_view);
draweeView.setImageURI("https://example.com/image.jpg");
Subsampling Scale Image View:
SubsamplingScaleImageView imageView = findViewById(R.id.imageView);
imageView.setImage(ImageSource.uri("https://example.com/image.jpg"));
Summary
Fresco is a more comprehensive image loading library with advanced features and optimizations, while Subsampling Scale Image View focuses specifically on displaying large images with zooming and panning capabilities. Fresco offers broader functionality but may be more complex, while Subsampling Scale Image View provides a simpler solution for specific use cases involving large, zoomable images.
An Android transformation library providing a variety of image transformations for Glide.
Pros of glide-transformations
- Offers a wide variety of image transformations (blur, crop, rotate, etc.)
- Integrates seamlessly with Glide, a popular image loading library
- Lightweight and easy to implement in existing projects
Cons of glide-transformations
- Limited to Glide library, not suitable for projects using other image loading solutions
- Doesn't provide advanced zooming and panning capabilities
- May not be optimal for handling very large images
Code Comparison
subsampling-scale-image-view:
SubsamplingScaleImageView imageView = new SubsamplingScaleImageView(context);
imageView.setImage(ImageSource.uri("/sdcard/full-image.jpg"));
imageView.setMaxScale(10f);
glide-transformations:
Glide.with(this)
.load("http://example.com/image.jpg")
.apply(bitmapTransform(new BlurTransformation(25)))
.into(imageView);
subsampling-scale-image-view focuses on efficient handling and display of large images with zooming and panning capabilities, while glide-transformations provides a variety of image transformations that can be easily applied when loading images with Glide. The choice between these libraries depends on the specific requirements of your project, such as image size, desired manipulations, and integration with existing image loading solutions.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Subsampling Scale Image View
A custom image view for Android, designed for photo galleries and displaying huge images (e.g. maps and building plans) without OutOfMemoryError
s. Includes pinch to zoom, panning, rotation and animation support, and allows easy extension so you can add your own overlays and touch event detection.
The view optionally uses subsampling and tiles to support very large images - a low resolution base layer is loaded and as you zoom in, it is overlaid with smaller high resolution tiles for the visible area. This avoids holding too much data in memory. It's ideal for displaying large images while allowing you to zoom in to the high resolution details. You can disable tiling for smaller images and when displaying a bitmap object. There are some advantages and disadvantages to disabling tiling so to decide which is best, see the wiki.
Guides
- Releases & downloads
- Installation and setup
- Image display notes & limitations
- Using preview images
- Handling orientation changes
- Advanced configuration
- Event handling
- Animation
- Extension
- Reference (JavaDocs)
Migration guides
Versions 3.9.0, 3.8.0 and 3.0.0 contain breaking changes. Migration instructions can be found in the wiki.
Download the sample app
Demo
Features
Image display
- Display images from assets, resources, the file system or bitmaps
- Automatically rotate images from the file system (e.g. the camera or gallery) according to EXIF
- Manually rotate images in 90° increments
- Display a region of the source image
- Use a preview image while large images load
- Swap images at runtime
- Use a custom bitmap decoder
With tiling enabled:
- Display huge images, larger than can be loaded into memory
- Show high resolution detail on zooming in
- Tested up to 20,000x20,000px, though larger images are slower
Gesture detection
- One finger pan
- Two finger pinch to zoom
- Quick scale (one finger zoom)
- Pan while zooming
- Seamless switch between pan and zoom
- Fling momentum after panning
- Double tap to zoom in and out
- Options to disable pan and/or zoom gestures
Animation
- Public methods for animating the scale and center
- Customisable duration and easing
- Optional uninterruptible animations
Overridable event detection
- Supports
OnClickListener
andOnLongClickListener
- Supports interception of events using
GestureDetector
andOnTouchListener
- Extend to add your own gestures
Easy integration
- Use within a
ViewPager
to create a photo gallery - Easily restore scale, center and orientation after screen rotation
- Can be extended to add overlay graphics that move and scale with the image
- Handles view resizing and
wrap_content
layout
Quick start
1) Add this library as a dependency in your app's build.gradle file.
dependencies {
implementation 'com.davemorrissey.labs:subsampling-scale-image-view:3.10.0'
}
If your project uses AndroidX, change the artifact name as follows:
dependencies {
implementation 'com.davemorrissey.labs:subsampling-scale-image-view-androidx:3.10.0'
}
2) Add the view to your layout XML.
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent" >
<com.davemorrissey.labs.subscaleview.SubsamplingScaleImageView
android:id="@+id/imageView"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
</LinearLayout>
3a) Now, in your fragment or activity, set the image resource, asset name or file path.
SubsamplingScaleImageView imageView = (SubsamplingScaleImageView)findViewById(id.imageView);
imageView.setImage(ImageSource.resource(R.drawable.monkey));
// ... or ...
imageView.setImage(ImageSource.asset("map.png"))
// ... or ...
imageView.setImage(ImageSource.uri("/sdcard/DCIM/DSCM00123.JPG"));
3b) Or, if you have a Bitmap
object in memory, load it into the view. This is unsuitable for large images because it bypasses subsampling - you may get an OutOfMemoryError
.
SubsamplingScaleImageView imageView = (SubsamplingScaleImageView)findViewById(id.imageView);
imageView.setImage(ImageSource.bitmap(bitmap));
Photo credits
- San Martino by Luca Bravo, via unsplash.com
- Swiss Road by Ludovic Fremondiere, via unsplash.com
About
Copyright 2018 David Morrissey, and licensed under the Apache License, Version 2.0. No attribution is necessary but it's very much appreciated. Star this project if you like it!
Top Related Projects
Implementation of ImageView for Android that supports zooming, by various touch gestures.
An image loading and caching library for Android focused on smooth scrolling
A powerful image downloading and caching library for Android
Powerful and flexible library for loading, caching and displaying images on Android.
An Android library for managing images and the memory they use.
An Android transformation library providing a variety of image transformations for Glide.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot