|
1 | | -# nativescript-camera |
2 | | -NativeScript plugin to empower using device camera. |
| 1 | +# NativeScript Camera |
3 | 2 |
|
4 | | -## Build |
| 3 | +Welcome to the `nativescript-camera` plugin for NativeScript framework |
5 | 4 |
|
6 | | -Run the create script in the root of the repo: |
| 5 | +## (Optional) Prerequisites / Requirements |
| 6 | + |
| 7 | +- installed [NativeScript-CLI](https://github.com/NativeScript/nativescript-cli) |
| 8 | + |
| 9 | +# Working with the camera plugin |
| 10 | + |
| 11 | +## Overview |
| 12 | + |
| 13 | +Almost every mobile application needs the option to capture, save and share images. |
| 14 | +The NativeScript camera plugin was designed for the first two parts of the job (taking a picture and optionally saving to device storage). |
| 15 | + |
| 16 | +## Installation |
| 17 | + |
| 18 | +Navigate to project folder and run NativeScript-CLI command |
| 19 | +``` |
| 20 | +tns plugin add nativescript-camera |
| 21 | +``` |
| 22 | + |
| 23 | +Plugin could be added as a standard npm dependency running command |
| 24 | +``` |
| 25 | +npm install nativescript-camera --save |
| 26 | +``` |
| 27 | + |
| 28 | +> Note: the `--save` flag will add the plugin as dependency in your package.json file |
| 29 | +
|
| 30 | +### Requesting permissions |
| 31 | + |
| 32 | +Newer API levels of Android and iOS versions are requiring explicit permissions in order the application |
| 33 | +to have access to the camera and to be able to save photos to the device. Once the user has granted permissions the camera module can be used. |
| 34 | + |
| 35 | +``` |
| 36 | +camera.requestPermissions(); |
| 37 | +``` |
| 38 | + |
| 39 | +> Note: Older versions won't be affected by the usage of the requestPermissions method. |
| 40 | +
|
| 41 | +## Usage |
| 42 | + |
| 43 | +### Requesting permissions |
| 44 | + |
| 45 | +Newer API levels of Android and iOS versions are requiring explicit permissions in order the application |
| 46 | +to have access to the camera and to be able to save photos to the device. Once the user has granted permissions the camera module can be used. |
| 47 | + |
| 48 | +``` |
| 49 | +camera.requestPermissions(); |
| 50 | +``` |
| 51 | + |
| 52 | +> Note: Older versions won't be affected by the usage of the requestPermissions method. |
| 53 | +
|
| 54 | +### Using the camera module to take a picture |
| 55 | + |
| 56 | +Using the camera module is relatively simple. |
| 57 | +However, there are some points that need a little bit more explanation. |
| 58 | + |
| 59 | +In order to use the camera module, just require it, as shown in Example 1: |
| 60 | + |
| 61 | +> Example 1: Require camera module in the application |
| 62 | +``` JavaScript |
| 63 | +var camera = require("nativescript-camera"); |
| 64 | +``` |
| 65 | +``` TypeScript |
| 66 | +import * as camera from "nativescript-camera"; |
7 | 67 | ``` |
8 | | -./create.sh |
| 68 | + |
| 69 | +Then you are ready to use it: |
| 70 | +> Example 2: How to take a picture and to recieve image asset |
| 71 | +``` JavaScript |
| 72 | +var imageModule = require("ui/image"); |
| 73 | +camera.takePicture() |
| 74 | + .then(function (imageAsset) { |
| 75 | + console.log("Result is an image asset instance"); |
| 76 | + var image = new imageModule.Image(); |
| 77 | + image.src = imageAsset; |
| 78 | + }).catch(function (err) { |
| 79 | + console.log("Error -> " + err.message); |
| 80 | + }); |
| 81 | +``` |
| 82 | +``` TypeScript |
| 83 | +import { Image } from "ui/image"; |
| 84 | +camera.takePicture({). |
| 85 | + then((imageAsset) => { |
| 86 | + console.log("Result is an image asset instance"); |
| 87 | + var image = new Image(); |
| 88 | + image.src = imageAsset; |
| 89 | + }).catch((err) => { |
| 90 | + console.log("Error -> " + err.message); |
| 91 | + }); |
9 | 92 | ``` |
10 | | -This will create a `nativescript-camera-*.tgz` file (* stands for version) within ./dist folder. |
| 93 | +
|
| 94 | +The code in __Example 2__ will start the native platform camera application. After taking the picture and tapping the button `Save` (Android) or `use image` (iOS), the promise will resolve the `then` part and image asset will be set as `src` of the `ui/image` control. |
| 95 | +
|
| 96 | +### Using the options to take memory efficient picture |
| 97 | +
|
| 98 | +__Example 2__ shows how to take a picture using the NativeScript camera module. However, it takes a huge image (even mid-level devices has a 5MP camera, which results in a image 2580x2048, which in bitmap means approximately 15 MB). In many cases you don't need such a huge picture to show an image with 100x100 size, so taking a big picture is just a waste of memory. The camera takePicture() method accepts an optional parameter that could help in that case. With that optional parameter, you could set some properties like: |
| 99 | +
|
| 100 | +* __width__: The desired width of the picture (in device independent pixels). |
| 101 | +* __height__: The desired height of the picture (in device independent pixels). |
| 102 | +* __keepAspectRatio__: A boolean parameter that indicates if the aspect ratio should be kept. |
| 103 | +* __saveToGallery__: A boolean parameter that indicates if the taken photo will be saved in "Photos" for Android and in "Camera Roll" in iOS |
| 104 | +* __cameraFacing__: Start with either the "front" or "rear" (default) camera of the device. The current implementation doesn't work on all Android devices, in which case it falls back to the default behavior. |
| 105 | +
|
| 106 | +What does `device independent pixels` mean? The NativeScript layout mechanism uses device-independent pixels when measuring UI controls. This allows you to declare one layout and this layout will look similar to all devices (no matter the device's display resolution). In order to get a proper image quality for high resolution devices (like iPhone retina and Android Full HD), camera will return an image with bigger dimensions. For example, if we request an image that is 100x100, on iPhone 6 the actual image will be 200x200 (since its display density factor is 2 -> 100*2x100*2). |
| 107 | +Setting the `keepAspectRatio` property could result in a different than requested width or height. The camera will return an image with the correct aspect ratio but generally only one (from width and height) will be the same as requested; the other value will be calculated in order to preserve the aspect of the original image. |
| 108 | +
|
| 109 | +__Example 3__ shows how to use the options parameter: |
| 110 | +> Example 3: How to setup `width`, `height`, `keepAspectRatio` and `saveToGallery` properties for the camera module |
| 111 | +
|
| 112 | +``` JavaScript |
| 113 | +var imageModule = require("ui/image"); |
| 114 | + |
| 115 | +var options = { width: 300, height: 300, keepAspectRatio: false, saveToGallery: true }; |
| 116 | +camera.takePicture(options) |
| 117 | + .then(function (imageAsset) { |
| 118 | + console.log("Size: " + imageAsset.options.width + "x" + imageAsset.options.height); |
| 119 | + console.log("keepAspectRatio: " + imageAsset.options.keepAspectRatio); |
| 120 | + console.log("Photo saved in Photos/Gallery for Android or in Camera Roll for iOS"); |
| 121 | + }).catch(function (err) { |
| 122 | + console.log("Error -> " + err.message); |
| 123 | + }); |
| 124 | +``` |
| 125 | +``` TypeScript |
| 126 | +import { Image } from "ui/image"; |
| 127 | + |
| 128 | +var options = { width: 300, height: 300, keepAspectRatio: false, saveToGallery: true }; |
| 129 | +camera.takePicture(options). |
| 130 | + then((imageAsset) => { |
| 131 | + console.log("Size: " + imageAsset.options.width + "x" + imageAsset.options.height); |
| 132 | + console.log("keepAspectRatio: " + imageAsset.options.keepAspectRatio); |
| 133 | + console.log("Photo saved in Photos/Gallery for Android or in Camera Roll for iOS"); |
| 134 | + }).catch((err) => { |
| 135 | + console.log("Error -> " + err.message); |
| 136 | + }); |
| 137 | +``` |
| 138 | +
|
| 139 | +### Check if the device has available camera |
| 140 | +
|
| 141 | +The first thing that the developers should check if the device has an available camera. |
| 142 | +The method isAvaiable will return true if the camera hardware is ready to use or false if otherwise. |
| 143 | +
|
| 144 | +``` |
| 145 | +var isAvailable = camera.isAvailable(); |
| 146 | +``` |
| 147 | +
|
| 148 | +> Note: This method will return false when used in iOS simulator (as the simulator does not have camera hardware) |
| 149 | + |
| 150 | +## License |
| 151 | +
|
| 152 | +Apache License Version 2.0, January 2004 |
0 commit comments