01. Setup

Installation

Library builds are published to the Maven central repository as AAR files. If you're using Gradle, simply add a dependency to your build.gradle file as shown below. An AndroidX build is available.

dependencies {
    // AndroidX
    compile 'com.davemorrissey.labs:subsampling-scale-image-view-androidx:3.10.0'
    // Legacy
    compile 'com.davemorrissey.labs:subsampling-scale-image-view:3.10.0'
}

Alternatively, you can download a library AAR file from the releases page and add it to your project, or clone the project and import the library subproject as a module in your app.

Basic usage

The recommended way of using the view is to add the element to your layout XML file, but configure it from code in your Activity or Fragment. This gives you the greatest control over its behaviour.

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>

Fragment or Activity

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"));

If using a drawable resource, you should normally store it in drawable-nodpi to avoid Android scaling it for the device's screen resolution.

Displaying a bitmap

If you have a Bitmap object, load it into the view. This is unsuitable for large images because it bypasses subsampling - you may get an OutOfMemoryError - but it's an easy way to add pan and zoom functionality for an image already in memory.

SubsamplingScaleImageView imageView = (SubsamplingScaleImageView)findViewById(id.imageView);
imageView.setImage(ImageSource.bitmap(bitmap));

If you have a Bitmap loaded by an image loader library such as Glide or Fresco, use the cachedBitmap method instead - this disables the view's default behaviour of recycling the bitmap when the view itself is recycled, allowing you to use the same bitmap again.

imageView.setImage(ImageSource.cachedBitmap(bitmap));

Layout notes

Normally you should add the view to a layout that has a fixed height and width (for example, the full size of the screen) and set its width and height to match_parent. There is limited support for using wrap_content for either width or height (not both) - the view will attempt to match its aspect ratio to that of the image when it loads.

If the view has padding, this is interpreted as a margin around the image at minimum scale. As you zoom in, the padded area is filled. Asymmetric padding (i.e. left != right or top != bottom) is supported, but while zooming the ratio of left/right and top/bottom padding is preserved until the image is wider or taller than the screen, and this may look odd.

Zero code

For a zero code approach to showing an image from your assets or resources, you need to define the custom namespace in your layout.

This method doesn't support most of the configuration options and cannot restore state after a screen orientation change.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:ssiv="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent" >

    <com.davemorrissey.labs.subscaleview.SubsamplingScaleImageView
        ssiv:assetName="map.png"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>
        
</LinearLayout>

To display a resource, use ssiv:src="@drawable/map".

A limited set of configuration options can be set from the layout. These can also be set from code.

Attribute	Type	Default	Description
assetName	string	n/a	Name of the image file in assets to be displayed.
src	resource	n/a	Drawable resource to be displayed.
panEnabled	boolean	true	Optionally disable pan gestures.
zoomEnabled	boolean	true	Optionally disable zoom gestures.
quickScaleEnabled	boolean	true	Optionally disable quick scale zoom gestures.
tileBackgroundColor	color	(transparent)	Set a background color to be rendered behind tiles when using images with alpha transparency.