README.md
1Subsampling Scale Image View
2===========================
3
4[](https://travis-ci.org/davemorrissey/subsampling-scale-image-view)
5
6A 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.
7
8The 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](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/02.-Displaying-images).
9
10#### Guides
11
12* [Releases & downloads](https://github.com/davemorrissey/subsampling-scale-image-view/releases)
13* [Installation and setup](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/01.-Setup)
14* [Image display notes & limitations](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/02.-Displaying-images)
15* [Using preview images](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/03.-Preview-images)
16* [Handling orientation changes](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/05.-Orientation-changes)
17* [Advanced configuration](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/07.-Configuration)
18* [Event handling](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/09.-Events)
19* [Animation](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/08.-Animation)
20* [Extension](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/10.-Extension)
21* [Reference (JavaDocs)](http://davemorrissey.github.io/subsampling-scale-image-view/javadoc/)
22
23#### Migration guides
24
25Versions 3.9.0, 3.8.0 and 3.0.0 contain breaking changes. Migration instructions can be found [in the wiki](https://github.com/davemorrissey/subsampling-scale-image-view/wiki/X.--Migration-guides).
26
27#### Download the sample app
28
29[](https://play.google.com/store/apps/details?id=com.davemorrissey.labs.subscaleview.sample)
30
31[Kotlin Sample App on GitHub](https://github.com/davemorrissey/ssiv-kotlin-sample)
32
33#### Demo
34
35
36
37## Features
38
39#### Image display
40
41* Display images from assets, resources, the file system or bitmaps
42* Automatically rotate images from the file system (e.g. the camera or gallery) according to EXIF
43* Manually rotate images in 90° increments
44* Display a region of the source image
45* Use a preview image while large images load
46* Swap images at runtime
47* Use a custom bitmap decoder
48
49*With tiling enabled:*
50
51* Display huge images, larger than can be loaded into memory
52* Show high resolution detail on zooming in
53* Tested up to 20,000x20,000px, though larger images are slower
54
55#### Gesture detection
56
57* One finger pan
58* Two finger pinch to zoom
59* Quick scale (one finger zoom)
60* Pan while zooming
61* Seamless switch between pan and zoom
62* Fling momentum after panning
63* Double tap to zoom in and out
64* Options to disable pan and/or zoom gestures
65
66#### Animation
67
68* Public methods for animating the scale and center
69* Customisable duration and easing
70* Optional uninterruptible animations
71
72#### Overridable event detection
73* Supports `OnClickListener` and `OnLongClickListener`
74* Supports interception of events using `GestureDetector` and `OnTouchListener`
75* Extend to add your own gestures
76
77#### Easy integration
78* Use within a `ViewPager` to create a photo gallery
79* Easily restore scale, center and orientation after screen rotation
80* Can be extended to add overlay graphics that move and scale with the image
81* Handles view resizing and `wrap_content` layout
82
83## Quick start
84
85**1)** Add `com.davemorrissey.labs:subsampling-scale-image-view:3.9.0` as a dependency in your build.gradle file.
86
87**2)** Add the view to your layout XML.
88
89 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
90 android:layout_width="match_parent"
91 android:layout_height="match_parent" >
92
93 <com.davemorrissey.labs.subscaleview.SubsamplingScaleImageView
94 android:id="@+id/imageView"
95 android:layout_width="match_parent"
96 android:layout_height="match_parent"/>
97
98 </LinearLayout>
99
100**3a)** Now, in your fragment or activity, set the image resource, asset name or file path.
101
102 SubsamplingScaleImageView imageView = (SubsamplingScaleImageView)findViewById(id.imageView);
103 imageView.setImage(ImageSource.resource(R.drawable.monkey));
104 // ... or ...
105 imageView.setImage(ImageSource.asset("map.png"))
106 // ... or ...
107 imageView.setImage(ImageSource.uri("/sdcard/DCIM/DSCM00123.JPG"));
108
109**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`.
110
111 SubsamplingScaleImageView imageView = (SubsamplingScaleImageView)findViewById(id.imageView);
112 imageView.setImage(ImageSource.bitmap(bitmap));
113
114## Photo credits
115
116* San Martino by Luca Bravo, via [unsplash.com](https://unsplash.com/photos/lWAOc0UuJ-A)
117* Swiss Road by Ludovic Fremondiere, via [unsplash.com](https://unsplash.com/photos/3XN-BNRDUyY)
118
119## About
120
121Copyright 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!
122
