From 0536cdc7708ede92513d758f9910b1b15228f530 Mon Sep 17 00:00:00 2001 From: Mattia Iavarone Date: Thu, 10 Aug 2017 23:08:59 +0200 Subject: [PATCH] New readme for new APIs --- README.md | 204 +++++++++++------- .../cameraview/CameraListener.java | 4 +- .../otaliastudios/cameraview/CameraView.java | 22 +- cameraview/src/main/res/values/attrs.xml | 2 +- 4 files changed, 149 insertions(+), 83 deletions(-) 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 - +