*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)*
*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).*
CameraKit is an easy to use utility to work with the Android Camera APIs. Everything at the moment is work in progress.
# CameraKit
CameraKit is an easy to use utility to work with the Android Camera APIs. Everything at the moment is work in progress, but it works well for pictures at least.
## Table of Contents
@ -10,43 +12,38 @@ CameraKit is an easy to use utility to work with the Android Camera APIs. Everyt
- Image and video capture seamlessly working with the same preview session.
- Automatic system permission handling.
- Automatic preview scaling.
- Create a `CameraView` of any size (not just presets!).
- Automatic output cropping to match your `CameraView` bounds.
- Multiple capture methods.
- `METHOD_STANDARD`: an image captured normally using the camera APIs.
- `METHOD_STILL`: a freeze frame of the `CameraView` preview (similar to SnapChat and Instagram) for devices with slower cameras.
- **Coming soon:**`METHOD_SPEED`: automatic capture method determination based on measured speed.
- Built-in continuous focus.
- Built-in tap to focus.
- **Coming soon:** Built-in pinch to zoom.
- [Center Crop](#center-crop)
- [Center Inside](#center-inside)
# Features
- Image and video capture seamlessly working with the same preview session. (TODO: remove this, use different sessions)
- System permission handling
- Dynamic sizing behavior
- Create a `CameraView` of any size (not just presets!)...
- Or let it adapt to the sensor preview size
- Automatic output cropping to match your `CameraView` bounds
- Multiple capture methods
- `CAPTURE_METHOD_STANDARD`: an image captured normally using the camera APIs.
- `CAPTURE_METHOD_FRAME`: a freeze frame of the `CameraView` preview (similar to SnapChat and Instagram) for devices with slower cameras
- Built-in tap to focus
- TODO: Built-in pinch to zoom
## Setup
Add __CameraKit__ to the dependencies block in your `app` level `build.gradle`:
```groovy
compile 'com.flurgle:camerakit:0.9.17'
```
For now, clone the repo and add it to your project.
TODO: publish to bintray.
## Usage
@ -60,7 +57,7 @@ To use CameraKit, simply add a `CameraView` to your layout:
android:adjustViewBounds="true" />
```
Make sure you override `onResume` and `onPause` in your activity, and make calls respectively to `CameraView.start()` and `CameraView.stop()`.
Make sure you override `onResume`, `onPause` and `onDestroy` in your activity, and call `CameraView.start()`, `stop()` and `destroy()`.
```java
@Override
@ -71,8 +68,14 @@ protected void onResume() {
@Override
protected void onPause() {
cameraView.stop();
super.onPause();
cameraView.stop();
}
@Override
protected void onDestroy() {
super.onDestroy();
cameraView.destroy();
}
```
@ -84,9 +87,7 @@ To capture an image just call `CameraView.captureImage()`. Make sure you setup a
camera.setCameraListener(new CameraListener() {
@Override
public void onPictureTaken(byte[] picture) {
super.onPictureTaken(picture);
// Create a bitmap
// Create a bitmap or a file...
Bitmap result = BitmapFactory.decodeByteArray(picture, 0, picture.length);
}
});
@ -96,13 +97,14 @@ camera.captureImage();
### Capturing Video
TODO: test size and orientation stuff.
To capture video just call `CameraView.startRecordingVideo()` to start, and `CameraView.stopRecordingVideo()` to finish. Make sure you setup a `CameraListener` to handle the video callback.
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).
How to capture pictures, either standard or frame. The frame option lets you capture and save a preview frame, which can be better with slower camera sensors, though the captured image can be blurry or noisy.
When you use `METHOD_STANDARD` (`camerakit:ckMethod="standard"`), images will be captured using the normal camera API capture method using the shutter.
When you use `METHOD_STILL` (`camerakit:ckMethod="still"`), images will be captured by grabbing a single frame from the preview. This behavior is the same as SnapChat and Instagram. This method has a higher rate of motion blur but can be a better experience for users with slower cameras.
When you use `METHOD_SPEED` (`camerakit:ckMethod="speed"`), images will be captured using both `METHOD_STANDARD` and `METHOD_SPEED`. After 6 image captures the camera will set itself to `METHOD_STANDARD` or `METHOD_STILL` permanently based on whichever is faster.
- - -
### `ckZoom`
[`off`](#off-2) [`pinch`](#pinch)
#### `off`
TODO: work in progress. Right now 'off' is the onlly option.
Either picture or video. This tells the library which permissions should be asked before starting the camera session. In the case of 'picture', we require the camera permissions. In the case of 'video', the record audio permission is asked as well.
You can handle permissions yourself in whatever way you want, but if you make a call to `CameraView.start()` without the `android.permission.CAMERA` permission, an exception would normally be thrown and your app would crash.
`CameraView` needs two permissions:
With CameraKit, we will automatically prompt for the `android.permission.CAMERA` permission if it's not available. If you want to handle it yourself, just make sure you don't call `CameraView.start()` until you acquire the permissions.
- `android.permission.CAMERA` : required
- `android.permission.RECORD_AUDIO` : required for capturing videos
You can handle permissions yourself and then call `CameraView.start()` once they are acquired. If they are not, `CameraView` will request permissions to the user based on the `permissionPolicy` that was set. In that case, you can restart the camera if you have a successful response from `onRequestPermissionResults()`.
## Dynamic Sizing Behavior
## Manifest file
You can setup the `CameraView` dimensions however you want. When your dimensions don't match the aspect ratio of the internal preview surface, the surface will be cropped minimally to fill the view. The behavior is the same as the `android:scaleType="centerCrop"` on an `ImageView`.
The library manifest file is not strict and only asks for camera permissions. This means that:
- If you wish to record videos, you should also add `android.permission.RECORD_AUDIO` to required permissions
You can use a mix of a fixed dimension (a set value or `match_parent`) as well as `wrap_content`. When you do this make sure you set `android:adjustViewBounds="true"` on the `CameraView`.
- If you want your app to be installed only on devices that have a camera, you should add:
When you do this the dimension set to `wrap_content` will automatically align with the true aspect ratio of the preview surface. In this case the whole preview will be visible with no cropping.
```xml
<uses-feature
android:name="android.hardware.camera"
android:required="true"/>
```
## Events
If you don't request this feature, you can use `CameraKit.hasCameras()` to detect if current device has cameras, and then start the camera view.
Make sure you can react to different camera events by setting up a `CameraListener` instance.
```java
camera.setCameraListener(new CameraListener() {
## Dynamic Sizing Behavior
@Override
public void onCameraOpened() {
super.onCameraOpened();
}
### Center crop
@Override
public void onCameraClosed() {
super.onCameraClosed();
}
You can setup the `CameraView` dimensions as you wish. Default behavior is that if your dimensions don't match the aspect ratio of the internal preview surface, the surface will be cropped to fill the view, just like `android:scaleType="centerCrop"` on an `ImageView`.
@Override
public void onPictureTaken(byte[] picture) {
super.onPictureTaken(picture);
}
### Center inside
@Override
public void onVideoTaken(File video) {
super.onVideoTaken(video);
}
If `android:adjustViewBounds` is set to true the library will try to adapt the view dimension to the chosen preview size. How? All dimensions set to `wrap_content` are streched out to ensure the view holds the whole preview. If both dimensions are `wrap_content`, this is exactly like `android:scaleType="centerInside"` on an `ImageView`.
Mattia Iavarone
7 years ago
