*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
## Table of Contents
@ -21,19 +21,11 @@ CameraView is a well documented, high-level library that makes capturing picture
@ -41,23 +33,23 @@ CameraView is a well documented, high-level library that makes capturing picture
# Features
# 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
- System permission handling
- Dynamic sizing behavior
- Dynamic sizing behavior
- Create a `CameraView` of **any** size
- Create a `CameraView` of **any size**
- Center inside or center crop behaviors
- Center inside or center crop behaviors
- Automatic output cropping to match your `CameraView` bounds
- Automatic output cropping to match your `CameraView` bounds
- Built-in tap to focus
- Built-in **grid drawing**
- Built-in pinch to zoom
- Built-in grid drawing
- Multiple capture methods
- Multiple capture methods
- Take high-resolution pictures with `capturePicture`
- Take high-resolution pictures with `capturePicture`
- Take quick snapshots as a freeze frame of the preview with `captureSnapshot` (similar to Snapchat and Instagram)
- 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
- Control flash, zoom, white balance, exposure correction and more
- `CameraUtils` to help with Bitmaps and orientations
- **Metadata** support for pictures and videos
- Metadata support for pictures and videos
- Automatically detected orientation tags
- Automatically detected orientation tags
- Plug in location tags with `setLocation()` API
- Plug in location tags with `setLocation()` API
- `CameraUtils` to help with Bitmaps and orientations
- Lightweight, no dependencies, just support `ExifInterface`
## Setup
## Setup
@ -65,13 +57,13 @@ For now, you must clone the repo and add it to your project.
## Usage
## 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
```xml
<com.otaliastudios.cameraview.CameraView
<com.otaliastudios.cameraview.CameraView
android:id="@+id/camera"
android:id="@+id/camera"
android:keepScreenOn="true"
android:keepScreenOn="true"
android:layout_width="match_parent"
android:layout_width="wrap_content"
android:layout_height="wrap_content" />
android:layout_height="wrap_content" />
```
```
@ -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.
To capture an image just call `CameraView.capturePicture()`. Make sure you setup a `CameraListener` to handle the image callback.
```java
```java
camera.setCameraListener(new CameraListener() {
camera.addCameraListener(new CameraListener() {
@Override
@Override
public void onPictureTaken(byte[] picture) {
public void onPictureTaken(byte[] picture) {
// Create a bitmap or a file...
// 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.
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.
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
```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
@Override
public void onCameraOpened(CameraOptions options) {}
public void onCameraOpened(CameraOptions options) {}
/**
* Notifies that the camera session was closed.
*/
@Override
@Override
public void onCameraClosed() {}
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
@Override
public void onPictureTaken(byte[] picture) {}
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
@Override
public void onVideoTaken(File video) {}
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
@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
@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
@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
## Dynamic Sizing Behavior
`CameraView` has a smart measuring behavior that will let you do what you want with a few flags.
`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:
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.
- `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.
- `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).
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
```xml
<com.otaliastudios.cameraview.CameraView
<com.otaliastudios.cameraview.CameraView
@ -220,8 +283,6 @@ This means that part of the preview is hidden, and the image output will contain
android:keepScreenOn="true"
android:keepScreenOn="true"
app:cameraFacing="back"
app:cameraFacing="back"
app:cameraFlash="off"
app:cameraFlash="off"
app:cameraFocus="continuous"
app:cameraZoom="off"
app:cameraGrid="off"
app:cameraGrid="off"
app:cameraSessionType="picture"
app:cameraSessionType="picture"
app:cameraCropOutput="true"
app:cameraCropOutput="true"
@ -235,15 +296,13 @@ This means that part of the preview is hidden, and the image output will contain
Focus behavior. Can be off, continuous (camera continuously tries to adapt its focus), tap (focus is driven by the user tap) and tapWithMarker (a marker is drawn on screen to indicate focusing).
Lets you enable built-in pinch-to-zoom behavior. This means that the camera will capture two-finger gestures and move the zoom value accordingly. Nothing is drawn on screen, but you can listen to `onZoomChanged` in your camera listener.
Lets you draw grids over the camera preview. Supported values are `off`, `grid3x3` and `grid4x4` for regular grids, and `phi` for a grid based on the golden ratio constant, often used in photography.
Lets you draw grids over the camera preview. Supported values are `off`, `grid3x3` and `grid4x4` for regular grids, and `phi` for a grid based on the golden ratio constant, often used in photography.
```java
```java
cameraView.setZoom(CameraConstants.GRID_OFF);
cameraView.setGrid(CameraConstants.GRID_OFF);
cameraView.setZoom(CameraConstants.GRID_3X3);
cameraView.setGrid(CameraConstants.GRID_3X3);
cameraView.setZoom(CameraConstants.GRID_4X4);
cameraView.setGrid(CameraConstants.GRID_4X4);
cameraView.setZoom(CameraConstants.GRID_PHI);
cameraView.setGrid(CameraConstants.GRID_PHI);
```
```
### cameraCropOutput
#### cameraCropOutput
Whether the output picture should be cropped to fit the aspect ratio of the preview surface.
Whether the output picture should be cropped to fit the aspect ratio of the preview surface.
This can guarantee consistency between what the user sees and the final output, if you fixed the camera view dimensions. This does not support videos.
This can guarantee consistency between what the user sees and the final output, if you fixed the camera view dimensions. This does not support videos.
Other APIs are provided and are well documented and commented in code.
Other APIs not mentioned above are provided, and are well documented and commented in code.
|Method|Description|
|Method|Description|
|------|-----------|
|------|-----------|
|`isStarted()`|Returns true if `start()` was called succesfully. This does not mean that camera is open or showing preview.|
|`mapGesture(Gesture, int)`|Maps a certain gesture to a certain action. No-op if the action is not supported.|
|`clearGesture(Gesture)`|Clears any action mapped to the given gesture.|
|`getCameraOptions()`|If camera was started, returns non-null object with information about what is supported.|
|`getCameraOptions()`|If camera was started, returns non-null object with information about what is supported.|
|`getExtraProperties()`|If camera was started, returns non-null object with extra information about the camera sensor. Not very useful at the moment.|
|`getExtraProperties()`|If camera was started, returns non-null object with extra information about the camera sensor. Not very useful at the moment.|
|`setZoom(float)`, `getZoom()`|Sets a zoom value, where 0 means camera zoomed out and 1 means zoomed in. No-op if zoom is not supported, or camera not started.|
|`setExposureCorrection(float)`, `getExposureCorrection()`|Sets exposure compensation EV value, in camera stops. No-op if this is not supported. Should be between the bounds returned by CameraOptions.|
|`setLocation(double, double)`|Sets latitude and longitude to be appended to picture/video metadata.|
|`setLocation(double, double)`|Sets latitude and longitude to be appended to picture/video metadata.|
|`setZoom(float)`|Sets a zoom value, where 0 means camera zoomed out and 1 means zoomed in. No-op if zoom is not supported, or camera not started.|
|`toggleFacing()`|Toggles the facing value between `FACING_FRONT` and `FACING_BACK`.|
|`setExposureCompensation(float)`|Sets exposure compensation EV value, in camera stops. No-op if this is not supported. Should be between the bounds returned by CameraOptions.|
|`toggleFlash()`|Toggles the flash value between `FLASH_OFF`, `FLASH_ON`, and `FLASH_AUTO`.|
|`isStarted()`|Returns true if `start()` was called succesfully. This does not mean that camera is open or showing preview.|
|`startAutoFocus(float, float)`|Starts an autofocus process at the given coordinates, with respect to the view dimensions.|
|`getPreviewSize()`|Returns the size of the preview surface. If CameraView was not constrained in its layout phase (e.g. it was `wrap_content`), this will return the same aspect ratio of CameraView.|
|`getPreviewSize()`|Returns the size of the preview surface. If CameraView was not constrained in its layout phase (e.g. it was `wrap_content`), this will return the same aspect ratio of CameraView.|
|`getSnapshotSize()`|Returns `getPreviewSize()`, since a snapshot is a preview frame.|
|`getSnapshotSize()`|Returns `getPreviewSize()`, since a snapshot is a preview frame.|
|`getPictureSize()`|Returns the size of the output picture. The aspect ratio is consistent with `getPreviewSize()`.|
|`getPictureSize()`|Returns the size of the output picture. The aspect ratio is consistent with `getPreviewSize()`.|
Take also a look at public methods in `CameraUtils`, `CameraOptions`, `ExtraProperties`.
## Permissions behavior
## Permissions behavior
`CameraView` needs two permissions:
`CameraView` needs two permissions:
@ -412,6 +458,7 @@ This is what was done since the library was forked. I have kept the original str
- *smart measuring and sizing behavior, replacing bugged `adjustViewBounds`*
- *smart measuring and sizing behavior, replacing bugged `adjustViewBounds`*
- *measure `CameraView` as center crop or center inside*
- *measure `CameraView` as center crop or center inside*
- *add multiple `CameraListener`s for events*
- *add multiple `CameraListener`s for events*
- *gesture framework support*
These are still things that need to be done, off the top of my head:
These are still things that need to be done, off the top of my head:
@ -423,11 +470,12 @@ These are still things that need to be done, off the top of my head:
- [x] better threading, for example ensure callbacks are called in the ui thread
- [x] better threading, for example ensure callbacks are called in the ui thread
- [x] pinch to zoom support
- [x] pinch to zoom support
- [x] exposure correction APIs
- [x] exposure correction APIs
- [ ] change demo app icon
- [x] change demo app icon
- [ ] refactor package name
- [x] refactor package name
- [x] new Gestures framework to map gestures to camera controls
- [x] heavily reduced dependencies
- [ ] `Camera2` integration
- [ ] `Camera2` integration
- [ ] publish to bintray
- [ ] publish to bintray
- [ ] attach operations (e.g. zoom, exposure correction) to vertical swipes or horizontal swipes
- [ ] add a `setPreferredAspectRatio` API to choose the capture size. Preview size will adapt, and then, if let free, the CameraView will adapt as well
- [ ] add a `setPreferredAspectRatio` API to choose the capture size. Preview size will adapt, and then, if let free, the CameraView will adapt as well
- [ ] animate grid lines similar to stock camera app
- [ ] animate grid lines similar to stock camera app
Mattia Iavarone
7 years ago