diff --git a/README.md b/README.md
index 03046b82..cb9de0ab 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ CameraView is a well documented, high-level library that makes capturing picture
-*This is a fork of [Dylan McIntyre's CameraKit-Android library](https://github.com/gogopop/CameraKit-Android), originally a fork of [Google's CameraView library](https://github.com/google/cameraview). The library at this point has been completely rewritten and refactored. See [below](#roadmap) for a list of what was done. This works better than any other library I have tried, and I would be grateful for any issue, suggestion or contribution.*
+*This is a fork of [CameraKit-Android library](https://github.com/gogopop/CameraKit-Android), originally a fork of [Google's CameraView library](https://github.com/google/cameraview). The library at this point has been completely rewritten and refactored. See [below](#roadmap) for a list of what was done. This works better than any other library I have tried, and I would be grateful for any issue, suggestion or contribution.*
## Table of Contents
@@ -21,19 +21,11 @@ CameraView is a well documented, high-level library that makes capturing picture
- [Capturing Images](#capturing-images)
- [Capturing Video](#capturing-video)
- [Other camera events](#other-camera-events)
+- [Gestures](#gestures)
- [Dynamic Sizing Behavior](#dynamic-sizing-behavior)
- [Center Inside](#center-inside)
- [Center Crop](#center-crop)
-- [XML Attributes](#xml-attributes)
- - [cameraSessionType](#camerasessiontype)
- - [cameraFacing](#camerafacing)
- - [cameraFlash](#cameraflash)
- - [cameraFocus](#camerafocus)
- - [cameraZoomMode](#camerazoommode)
- - [cameraCropOutput](#cameracropoutput)
- - [cameraJpegQuality](#camerajpegquality)
- - [cameraWhiteBalance](#camerawhitebalance)
- - [cameraGrid](#cameragrid)
+- [Camera Controls](#camera-controls)
- [Other APIs](#other-apis)
- [Permissions Behavior](#permissions-behavior)
- [Manifest file](#manifest-file)
@@ -41,23 +33,23 @@ CameraView is a well documented, high-level library that makes capturing picture
# Features
-- Seamless image and video capturing, even within the same session
+- Seamless image and video capturing
+- **Gestures** support (tap to focus, pinch to zoom and much more)
- System permission handling
- Dynamic sizing behavior
- - Create a `CameraView` of **any** size
+ - Create a `CameraView` of **any size**
- Center inside or center crop behaviors
- Automatic output cropping to match your `CameraView` bounds
-- Built-in tap to focus
-- Built-in pinch to zoom
-- Built-in grid drawing
+- Built-in **grid drawing**
- Multiple capture methods
- Take high-resolution pictures with `capturePicture`
- Take quick snapshots as a freeze frame of the preview with `captureSnapshot` (similar to Snapchat and Instagram)
-- Control flash, focus, zoom, white balance, exposure correction
-- `CameraUtils` to help with Bitmaps and orientations
-- Metadata support for pictures and videos
+- Control flash, zoom, white balance, exposure correction and more
+- **Metadata** support for pictures and videos
- Automatically detected orientation tags
- Plug in location tags with `setLocation()` API
+- `CameraUtils` to help with Bitmaps and orientations
+- Lightweight, no dependencies, just support `ExifInterface`
## Setup
@@ -65,13 +57,13 @@ For now, you must clone the repo and add it to your project.
## Usage
-To use CameraView engine, simply add a `CameraView` to your layout:
+To use the CameraView engine, simply add a `CameraView` to your layout:
```xml
```
@@ -102,7 +94,7 @@ protected void onDestroy() {
To capture an image just call `CameraView.capturePicture()`. Make sure you setup a `CameraListener` to handle the image callback.
```java
-camera.setCameraListener(new CameraListener() {
+camera.addCameraListener(new CameraListener() {
@Override
public void onPictureTaken(byte[] picture) {
// Create a bitmap or a file...
@@ -121,7 +113,7 @@ You can also use `camera.captureSnapshot()` to capture a preview frame. This is
To capture video just call `CameraView.startRecordingVideo(file)` to start, and `CameraView.stopRecordingVideo()` to finish. Make sure you setup a `CameraListener` to handle the video callback.
```java
-camera.setCameraListener(new CameraListener() {
+camera.addCameraListener(new CameraListener() {
@Override
public void onVideoTaken(File video) {
// The File is the same you passed before.
@@ -129,7 +121,13 @@ camera.setCameraListener(new CameraListener() {
}
});
-File file = ...; // Make sure you have permissions to write here.
+// Select output file. Make sure you have write permissions.
+File file = ...;
+
+// Record a 2500 ms video:
+camera.startRecordingVideo(file, 2500);
+
+// Full version
camera.startRecordingVideo(file);
camera.postDelayed(new Runnable() {
@Override
@@ -139,45 +137,108 @@ camera.postDelayed(new Runnable() {
}
}, 2500);
-// Shorthand:
-camera.startRecordingVideo(file, 2500);
```
### Other camera events
-Make sure you can react to different camera events by setting up a `CameraListener` instance.
+Make sure you can react to different camera events by setting up one or more `CameraListener` instances.
```java
-camera.setCameraListener(new CameraListener() {
+camera.addCameraListener(new CameraListener() {
+ /**
+ * Notifies that the camera was opened.
+ * The options object collects all supported options by the current camera.
+ */
@Override
public void onCameraOpened(CameraOptions options) {}
+
+ /**
+ * Notifies that the camera session was closed.
+ */
@Override
public void onCameraClosed() {}
+
+ /**
+ * Notifies that a picture previously captured with capturePicture()
+ * or captureSnapshot() is ready to be shown or saved.
+ *
+ * If planning to get a bitmap, you can use CameraUtils.decodeBitmap()
+ * to decode the byte array taking care about orientation.
+ */
@Override
public void onPictureTaken(byte[] picture) {}
+
+ /**
+ * Notifies that a video capture has just ended. The file parameter is the one that
+ * was passed to startCapturingVideo(File), or a fallback video file.
+ */
@Override
public void onVideoTaken(File video) {}
-
+
+
+ /**
+ * Notifies that user interacted with the screen and started focus with a gesture,
+ * and the autofocus is trying to focus around that area.
+ * This can be used to draw things on screen.
+ */
@Override
- public void onFocusStart(float x, float y) {}
+ public void onFocusStart(PointF point) {}
+
+ /**
+ * Notifies that a gesture focus event just ended, and the camera converged
+ * to a new focus (and possibly exposure and white balance).
+ */
@Override
- public void onFocusEnd(boolean successful, float x, float y) {}
+ public void onFocusEnd(boolean successful, PointF point) {}
+
+ /**
+ * Noitifies that a finger gesture just caused the camera zoom
+ * to be changed. This can be used, for example, to draw a seek bar.
+ */
@Override
- public void onZoomChanged(float zoomValue, PointF[] fingers) {}
+ public void onZoomChanged(float newValue, float[] bounds, PointF[] fingers) {}
+
+
+ /**
+ * Noitifies that a finger gesture just caused the camera exposure correction
+ * to be changed. This can be used, for example, to draw a seek bar.
+ */
+ public void onExposureCorrectionChanged(float newValue, float[] bounds, PointF[] fingers) {}
});
```
+## Gestures
+
+`CameraView` listen to lots of different gestures inside its bounds. You have the chance to map these gestures to particular actions or camera controls, using `mapGesture()`. This lets you emulate typical behaviors in a single line:
+
+```java
+cameraView.mapGesture(Gesture.PINCH, CameraConstants.GESTURE_ACTION_ZOOM); // Pinch to zoom!
+cameraView.mapGesture(Gesture.TAP, CameraConstants.GESTURE_ACTION_FOCUS_WITH_MARKER); // Tap to focus!
+cameraView.mapGesture(Gesture.LONG_TAP, CameraConstants.GESTURE_ACTION_CAPTURE); // Long tap to shoot!
+```
+
+Simple as that. More gestures are coming. There are two things to be noted:
+
+- Not every mapping is valid. For example, you can't control zoom with long taps, or start focusing by pinching.
+- Some actions might not be supported by the sensor. Check out `CameraOptions` to know what's legit and what's not.
+
+|Gesture|XML|Description|Can be mapped to|
+|-------|---|-----------|----------------|
+|`PINCH`|`cameraGesturePinch`|Pinch gesture, typically assigned to the zoom control.|`zoom` `exposureCorrection` `none`|
+|`TAP`|`cameraGestureTap`|Single tap gesture, typically assigned to the focus control.|`focus` `focusWithMarker` `capture` `none`|
+|`LONG_TAP`|`cameraGestureLongTap`|Long tap gesture.|`focus` `focusWithMarker` `capture` `none`|
+
+
## Dynamic Sizing Behavior
-`CameraView` has a smart measuring behavior that will let you do what you want with a few flags.
-Measuring is controlled simply by `layout_width` and `layout_height` attributes, with this meaning:
+`CameraView` has a smart measuring behavior that will let you do what you want with a few flags. Measuring is controlled simply by `layout_width` and `layout_height` attributes, with this meaning:
- `WRAP_CONTENT` : try to stretch this dimension to respect the preview aspect ratio.
- `MATCH_PARENT` : fill this dimension, even if this means ignoring the aspect ratio.
@@ -210,7 +271,9 @@ You can emulate a **center crop** behavior by setting both dimensions to fixed v
This means that part of the preview is hidden, and the image output will contain parts of the scene that were not visible during the capture. If this is a problem, see [cameraCropOutput](#cameracropoutput).
-## XML Attributes
+## Camera controls
+
+Most camera parameters can be controlled through XML attributes or linked methods.
```xml
-
+