The Camera API provides access to your device's Camera(s). Use this API to give users the ability to take a photo via one of the device's cameras and return it to the application. Photos can either be stored on the device and optionally transfered to an online server using the Network API or can be returned as a DataURI object for storing or display. ## Enabling the API In order to use this API you must include the following extension in your `build.yml` :::ruby extensions: ["mediacapture"] ## JavaScript Usage Be sure to review the [JavaScript API Usage](/guide/api_js) guide for important information about using this API in JavaScript ## Ruby Usage Be sure to review the [Ruby API Usage](/guide/api_ruby) guide for important information about using this API in Ruby ## Enabling the API There are two methods of enabling the Camera API: * Include all ebapi modules or * Include only the API modules you need For either of these methods, you'll need to include files from the `/Enterprise Browser/JavaScript Files/Enterprise Browser` directory on the computer that you installed the Enterprise Browser. ### Include all JS API modules To include all JS APIs, you must copy the ebapi-modules.js file to a location accessible by your app's files and include the JavaScript file in your app. For instance, to include the modules file in your index.html, with the file in the same directory as your index.html, you would add the following line to the <head> section of your index.html: :::html <script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script> > Note: that the pathing for this file is relative to the current page. This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion. ### Include only the modules you need To include single APIs, you must first include the `ebapi.js` in your HTML as well as the API file you want to use. For instance, to use the Camera API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML. :::html <script type="text/javascript" charset="utf-8" src="ebapi.js"></script> <script type="text/javascript" charset="utf-8" src="eb.camera.js"></script> The ebapi.js file is necessary for all single API inclusions. Android, iOS, WM, CE, WP8 WM, Android Back camera. This is not supported in WM/CE devices. Front camera. This is not supported in WM/CE devices. Camera is an imager. This is supported only in WM/CE devices. Camera is color camera. This is supported only in WM/CE devices. JPG compression. PNG compression. This shall provide the image path. This is a base 64 encoding of the image and can be used to easily embed the image on the page or store the image in a database. On some consumer devices, captured image will be rotated 90 degrees while displaying. A colour image is captured. A grayscale image is captured. Flash will be used. Flash will not be used. Flash will be used if lighting conditions deem it necessary. This is not supported in WM/CE devices. Flash with red eye reduction is used. This is supported only in Android devices. The flash is turned on in torch mode. This is supported only in Android devices. Switches the imager's aim to ON Switches the imager's aim to OFF These properties are used to configure the Camera. Android, iOS, WP8, WM, CE WM, CE, Android This property is device specific. The value for this property can be either 'back' or 'front' in the case of Android/iOS/WP8 devices.In the case of WM/CE it could be either 'imager' or 'color'. WM/CE devices will use 'color'as default and if color camera not available the default value will be 'imager'. Android/iOS/WP8 devices will use 'back'as default and if back camera not available the default value will be 'front', This Property shall return one among the values mentioned in constant section which starts with CAMERA_TYPE_... This property is device specific. The value for this property can be either 'back' or 'front' in the case of Android devices.In the case of windows it could be either 'imager' or 'color'. WM/CE devices will use 'color'as default and if color camera not available the default value will be 'imager'. Android devices will use 'back'as default and if back camera not available the default value will be 'front'. This Property shall return one among the values mentioned in constant section which starts with CAMERA_TYPE_... Android, iOS, WP8, WM, CE WM, CE, Android The maximum width of images which can be captured. This is measured in pixels. On WM/CE devices this is applicable only for color camera. Imager does not support this property. Android, iOS, WP8, WM, CE WM, CE, Android The maximum height of images which can be captured. This is measured in pixels. On WM/CE devices this is applicable only for color camera. Imager does not support this property. Android, WP8, WM, CE, iOS WM, CE, Android List of resolutions (width and height in pixels) supported by the camera. On WM/CE devices this feature is supported only by color camera and it is not supported by imager. Refer example section for more details. 2.0.0 Android, iOS, WM, CE, WP8 WM, CE, Android Camera hardware is limited to taking photos in a finite number of resolutions, eg 2048x1536, 640x480 etc. Specifying a desiredWidth will request to take the photo with the specified width but if it is not supported by the hardware then the closest match will be selected. The callback received when a photo is taken contains the actual resolution of the captured photo. 2.0.0 Android, iOS, WM, CE, WP8 WM, CE, Android Camera hardware is limited to taking photos in a finite number of resolutions, eg 2048x1536, 640x480 etc. Specifying a desiredHeight will request to take the photo with the specified height but if it is not supported by the hardware then the closest match will be selected. The callback received when a photo is taken contains the actual resolution of the captured photo. 4.0.0 Android, iOS, WM, CE, WP8 WM, CE, Android The image file path without file extension to store captured image in subsequent calls to takePicture() or capture(). Default filename will be IMG_timestamp and will be saved under root directory. The filename extension will be added automatically according to compressionFormat property value. In Wp8, only filename can be changed, by default the path shall be under picture=>CameraRoll 4.0.0 JPG is supported on all devices, Android, WP8 and Windows Mobile does not support PNG images Android, iOS, WM, CE, WP8 WM, CE, Android The format of the captured image in subsequent calls to takePicture(). If you do not define this property when you use choose_picture with iOS, the type of image in Gallery will be recognized, and the same format will be used for saving the image to applications data. In windows and WP8 devices the format will be always jpg type. This Property shall accept/return one among the values mentioned in constant section which starts with COMPRESSION_FORMAT_... The format of the captured image in subsequent calls to takePicture(). On windows devices the format will be always .jpg type. This Property shall accept/return one among the values mentioned in constant section which starts with COMPRESSION_FORMAT_... 4.0.0 Android, iOS, WM, CE, WP8 WM, CE, Android Specifies the way to return the captured image to the application. This Property shall accept/return one among the values mentioned in constant section which starts with OUTPUT_FORMAT_... Specifies the way to return the captured image to the application. This Property shall accept/return one among the values mentioned in constant section which starts with OUTPUT_FORMAT_... 2.0.0 Android, iOS Android Where supported by the hardware this property can be used to select whether to capture a color or a grayscale image. This Property shall accept/return one among the values mentioned in constant section which starts with COLOR_MODEL_... Where supported by the hardware this property can be used to select whether to capture a color or a grayscale image. This Property shall accept/return one among the values mentioned in constant section which starts with COLOR_MODEL_... 2.0.0 iOS Enables post photo capture image customizing; image will captured reduced to screen size (not full size of camera sensor). 2.0.0 Android, WM, CE, iOS, WP8 Android, WM, CE Specifies the flash behavior when taking a picture. This Property shall accept/return one among the values mentioned in constant section which starts with FLASH_... Specifies the flash behavior when taking a picture. This Property shall accept/return one among the values mentioned in constant section which starts with FLASH_... 2.0.0 iOS,Android Android If true, the picture you take will be added to the device photo gallery. 4.0.0 Android, WM, CE Android, WM, CE Path to a sound file resident on the device which will be played when the image is captured. 4.0.0 WM, CE In cases where the resident camera application on the device is not used this API is used to control the position of the viewfinder preview window when taking a photo. 4.0.0 WM, CE In cases where the resident camera application on the device is not used this API is used to control the position of the viewfinder preview window when taking a photo. 4.0.0 WM, CE In cases where the resident camera application on the device is not used this API is used to control the position of the viewfinder preview window when taking a photo. 4.0.0 WM, CE In cases where the resident camera application on the device is not used this API is used to control the position of the viewfinder preview window when taking a photo. 4.0.0 Android Setting the value of this property to "true", shall open the System ViewFinder with its properties. Applicable to takePicture() and choosePicture() both. None of the Rho camera properties shall be applicable except desiredWidth and desiredHeight (desired size aplly if useRealBitmapResize enabled). 4.0.0 Android Setting the value of this property to "true", shall use real resize captured or selected Image and scale image exactly to desired size (with keep aspect ratio). For example 3000x2000 with desired 1500x1500 will be resized to 1500x1000. WM, CE Specifies the aim behaviour when taking a picture. Applicable only for imager module. This Property shall accept/return one among the values mentioned in constant section which starts with AIM_... Specifies the aim behaviour when taking a picture. Applicable only for imager module. This Property shall accept/return one among the values mentioned in constant section which starts with AIM_... Android, WM, CE, iOS, WP8 Android, WM, CE Returns the cameras present on your device, allowing you to access your device's front or back camera. Array of objects. Android, iOS, WP8, WM, CE Android, WM, CE Returns the camera of requested type if that camera exist - else return nil. CameraType: 'back' or 'front' in the case of Android, iOS and WP8 and 'color' or 'imager' in the case of WM, CE devices CameraType: 'back' or 'front' in the case of Android and 'color' or 'imager' in the case of WM, CE devices Camera with requested type or nil if not requested type does not exist. Refer example section for more details. Android, WM, CE, iOS, WP8 Android, WM, CE Start the camera application to take a picture. The user can capture the displayed image by interacting with the resident camera app. In Windows, this method always shows the preview in full screen and user can use the native button to capture the image. On wp8,wm when 'outputFormat' is 'image' then imageUri/image_uri shall have only Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when 'outputFormat' is 'image' > Note: To display an image, it is recommended that you use the full path to the image instead of a relative path. To do this, you can use the [`expandDatabaseBlobFilePath`](Application#mexpandDatabaseBlobFilePath) method of the [Application module](Application) as such: ##### Ruby :::ruby Rho::RhoApplication.expandDatabaseBlobFilePath(x.image_uri) ##### JavaScript :::js Rho.RhoApplication.expandDatabaseBlobFilePath(x.image_uri) Provide a set of properties to configure the camera, for example to specify the flashMode or compressionFormat. Not providing properties to this function will use the Camera's default properties, or those previously set on the Camera instance. Android, WM, CE, iOS, WP8 Android, WM, CE Whether or not the image was successfully captured. The returned string will be one of 'ok', 'cancel' or 'error'. Android, WM, CE, iOS, WP8 Android, WM, CE If the specified 'outputFormat' was 'image' then this field is the URI to the taken image stored on the device.On wp8,wm when 'outputFormat' is 'image' then imageUri shall have only Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when 'outputFormat' is 'image', this image will have an auto-generated name. If the specified 'outputFormat' was 'dataUri' then this field will be the image encoded as a Data URI, In Wp8 dataUri shall provide the thumbnail for the picture taken, It is recommended to use Image over dataUri Android, WM, CE, iOS, WP8 Android, WM, CE The actual height of the image that was captured, this may differ from the requested height as the Camera will only support a finite resolutions. Android, WM, CE, iOS, WP8 Android, WM, CE The actual width of the image that was captured, this may differ from the requested width as the Camera will only support a finite resolutions. Android, WM, CE, iOS Android, WM, CE The format in which the image was captured, either 'png' or 'jpg'. Android, WM, CE, iOS, WP8 Android, WM, CE If the returned status is 'error' then this field will contain more information on the error. To maintain backward compatibility WM and Android platforms provides message for cancel status as well. Android, WM, CE, iOS, WP8 Android, WM, CE It is recommended to use imageUri in preference to this parameter.On wp8,wm when 'outputFormat' is 'image' then image_uri shall have only Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when 'outputFormat' is 'image' Android, WM, CE, iOS, WP8 Android, WM, CE It is recommended to use imageHeight in preference to this parameter. Android, WM, CE, iOS, WP8 Android, WM, CE It is recommended to use imageWidth in preference to this parameter. Android, WM, CE, iOS Android, WM, CE It is recommended to use imageFormat in preference to this parameter. Shows the preview in user configurable viewer window. WM, CE WM, CE Provide a set of properties to configure the camera. Not providing properties to this function will use the Camera's default properties, or those previously set on the Camera instance. Hides the preview opened by using showPreview. WM, CE WM, CE Capture the image and save it to a file. WM, CE WM, CE Whether or not the image was successfully captured. The returned string will be one of 'ok' or 'error'. If the specified 'outputFormat' was 'image' then this field is the URI to the taken image stored on the device, this image will have an auto-generated name.On wm when 'outputFormat' is 'image' then this field shall have only Image name with \ sign, If the specified 'outputFormat' was 'dataUri',then this field will be the image encoded as a Data URI. The actual height of the image that was captured, this may differ from the requested height as the Camera will only support a finite resolutions. The actual width of the image that was captured, this may differ from the requested width as the Camera will only support a finite resolutions. The format in which the image was captured, either 'png' or 'jpg'. If the returned status is 'error' then this field will contain more information on the error. Choose a picture from the album. Android, WM, CE, WP8, iOS Android, WM, CE Provide a set of properties to configure an image, for example to specify the image size or color mode. In WM/CE,Android and WP8 devices user can only specify the outputFormat in the property bag. In iOS devices user can specify next options: compressionFormat, desiredWidth, desiredHeight, outputFormat, colorModel, enableEditing. In Wp8 dataUri shall provide the thumbnail for the picture taken, It is recommended to use Image over dataUri.On wp8, wm when 'outputFormat' is 'image' then imageUri or image_uri shall have Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when 'outputFormat' is 'image' Provide a set of properties to configure an image, for example to specify the image size or color mode. In WM/CE,Android devices user can only specify the outputFormat in the property bag. Not providing properties to this function will use the Camera's default properties, or those previously set on the Camera instance. Whether or not the image was successfully chosen from the gallery. The returned string will be one of 'ok', 'cancel' or 'error'. Android, WM, CE, iOS, WP8 Android, WM, CE The URI to the chosen image. The height of the image. The width of the image. The format of the image, either 'png' or 'jpg'. If the returned status is 'error' then this field will contain more information on the error. To maintain backward compatibility WM and Android platforms provides message for cancel status as well. Android, WM, CE, iOS, WP8 Android, WM, CE It is recommended to use imageUri in preference to this parameter. It is recommended to use imageHeight in preference to this parameter. It is recommended to use imageWidth in preference to this parameter. It is recommended to use imageFormat in preference to this parameter. iOS, Android Android Save an image to the device gallery. The real path to the image that is to be saved in the device gallery. You need to use the RhoApplication method `expandDatabaseBlobFilePath` to have the real path, such as `Rho::RhoApplication::expandDatabaseBlobFilePath(img.image_uri)`. 4.0.0
Take an image with as little code as possible, using all default values. :show_picture, :query => {:image => Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"])})) else # Otherwise we are done here Rho::WebView.navigate(url_for(:action => :index)) end end ]]> tag, we will be able to see the image that was just captured $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"])); } } ]]>
On devices with more than one camera, you can select which camera to use for taking pictures. :picture_taken_callback)) end # choose_camera.erb ]]> var cameras = []; function choose_camera() { // get all available cameras cameras = Rho.Camera.enumerate(); // build an HTML list var cameraList = ""; // make camera list visible to the user $("#camera_list").html(cameraList); } function take_picture_with_camera(cameraIndex) { var camera = cameras[cameraIndex]; camera.takePicture({}, picture_taken_callback); } ]]>
Apart from taking new pictures, you can also save images to the built-in gallery. In the following examples, the picture we are adding to the gallery is one that was just taken with the camera, but you can add any other image you can access by filename. :picture_taken_callback_save_to_gallery)) end def picture_taken_callback_save_to_gallery # Did we really take a picture? if (@params["status"]=="ok") # If so, save it to the gallery Rho::Camera.copyImageToDeviceGallery(Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"])) end Rho::WebView.navigate(url_for(:action => :index)) end ]]>
You can tweak multiple options to get an image exactly as you need it :show_picture, :query => {:image => Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"])})) else # Otherwise we are done here Rho::WebView.navigate(url_for(:action => :index)) end end ]]> tag $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"])); } } ]]>
You can get all available camera properties in a single call. <% @properties.each_pair do |name,value| %>
  • <%= name %> : <%= value %>
  • <% end %> ]]>
    "; // Get all capabilities of the camera... var capabilities = Rho.Camera.getAllProperties(); // ... compose a nicely formatted list with their names and values ... for (var capability in capabilities) { capabilitiesList+="
  • "+capability+": "+capabilities[capability]+"
  • "; } capabilitiesList += ""; // ... and show it $("#camera_capabilities").html(capabilitiesList); } ]]>
    Apart from taking new pictures, the Camera API also lets you access existing images on the device's gallery. :picture_taken_callback)) end def picture_taken_callback # Did we really take a picture? if (@params["status"]=="ok") # If so, show it Rho::WebView.navigate(url_for(:action => :show_picture, :query => {:image => Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"])})) else # Otherwise we are done here Rho::WebView.navigate(url_for(:action => :index)) end end ]]> tag $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"])); } } ]]>
    Camera API also lets you access camera instance by cameraType.
    Camera resolution is hardware specific. Camera API supports getting the supported resolutions of a camera instance.
    The capability for SDCard has already been granted on build, and any capability added by you will be ignored. This being the case, the following extensions will always be able to write to the SD card by default. In some of the WM/CE devices, though user has opted for a full screen, preview rendering size is decided by the driver. DataUri output is highly dependent on virtual space availability. DataUri may fail(Unresponsive/Reboot/Degraded Performance/Never load) in certain devices; recommended to use image path in such devices. Image uri display is dependent on browser capability. WP8 does not support getSupportedProperties and SetSupportedProperties Grayscale is supported only in consumer android devices for front camera Only valid and non-empty values for properties are supported in Android and iOS Due to platform limitation imager and color camera is not supported in ruby applications for CE5 and CE6 devices. All WM and CE7 devices automatically turn off both color and imager cameras when the device is suspended. User has to restart the camera on resume. Whereas CE5 (eg:MC9000) and CE6 (eg: MC31) devices retain the preview on resuming from suspend state. Image captured in few devices(eg: Samsung), irrespective of picture taken (Landscape/Portrait) , will always save in Landscape Mode, Even though on the device it appears as captured(landscape/Portrait), when the same is copied to Desktop, you can see that it will be in Landscape Mode.This is default behaviour of the device Due to platform limitation devices such as ES400, MC65 and MC67 does not support color camera. In devices having low processor, lower resolution image capture may show a small area of preview on black background at the time of transition back to application. Choose picture List must contain atleast 4 Images Name to show the list. Whenever an image is taken from Rho camera,on opening galery or choose picture, we can see a black image, when system refreshes the gallery this will be gone.