The Camera API provides access to the device camera(s). Use this API to give users the ability to take a photo via one of the cameras and return it to the application. Photos can either be stored on the device as an image file or returned as a DataURI object for storage and/or display. Optionally, image files also can be transfered to online storage using the Network API. ## Enabling the API To use this API, the following extension must be included in the `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 Android, iOS, WM, CE, WP8 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 uri. This can be used to display image directly on the page. An example is shown in the example section 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. If this value used for setting the outputFormat property, the takePicture or capture API will return imageUri as the path to the saved image in the device. User can use this image path to transfer the file to an http server if required. An example is given to demonstrate, transferring a file to http server.This property is not applicable for Android and windows phone 8. 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 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_... Android, iOS, WP8, WM, CE 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 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 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 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 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 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 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_... 4.0.0 Android, iOS, WM, CE, WP8 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 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 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 If true, the picture you take will be added to the device photo gallery. 4.0.0 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. 4.0.0 Android Setting the value of this property to "true", shall use rotation captured Bitmap by EXIF Info. It is actual for Samsung devices - they do not rotate captured images but just add EXIF info about rotation. Default loader do not apply this info. If this property is true then Rhodes rotate image and save rotated without EXIF rotate info. 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_... Android, WM, CE, iOS, WP8 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 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 Camera with requested type or nil if not requested type does not exist. Refer example section for more details. Android, WM, CE, iOS, WP8 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 Whether or not the image was successfully captured. The returned string will be one of 'ok', 'cancel' or 'error'. Android, WM, CE, iOS, WP8 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. If the specified 'outputFormat' was 'imagePath' then this field will have the image path on the device. User can use image path to transfer image over http. Android, WM, CE, iOS, WP8 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 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 The format in which the image was captured, either 'png' or 'jpg'. Android, WM, CE, iOS, WP8 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 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. If the specified 'outputFormat' was 'imagePath' then this field will have the image path on the device. User can use image path to transfer image over http. Android, WM, CE, iOS, WP8 It is recommended to use imageHeight in preference to this parameter. Android, WM, CE, iOS, WP8 It is recommended to use imageWidth in preference to this parameter. Android, WM, CE, iOS It is recommended to use imageFormat in preference to this parameter. Shows the preview in user configurable viewer window. 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 Capture the image and save it to a file. 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. 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. If the specified 'outputFormat' was 'imagePath' then this field will have the image path on the device. User can use image path to transfer image over http. 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 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' 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 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. If the specified 'outputFormat' was 'imagePath' then this field will have the image path on the device. User can use image path to transfer image over http. 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 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. If the specified 'outputFormat' was 'imagePath' then this field will have the image path on the device. User can use image path to transfer image over http. 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 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.
    This example demonstrate how user can transfer an image to http server. This will be useful when application is running on a remote server.
    This example demonstrate how user can dispaly an image using image uri. The callback will return a image uri when outputFormat is set to 'image'
    SD Card access is enabled by default; grants of additional access will be ignored. The following extensions are able to write to the SD card by default. Despite a user-selected full screen mode, preview rendering size will be overridden by the driver on some WM/CE devices. DataUri output is dependent on availability of virtual space. DataUri may fail, be unresponsive, cause reboot, degraded performance or fail to load in certain devices. In such cases, image path is recommended. Image Uri display is dependent on browser capability. WP8 does not support getSupportedProperties or SetSupportedProperties. Grayscale is supported only in the front camera of Android consumer devices. Only valid and non-empty values for properties are supported in Android and iOS. Due to platform limitations, imager and color camera are 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 must restart the camera to resume. Whereas CE5 (eg: MC9000) and CE6 (eg: MC31) devices retain the preview on resuming from suspend state. In some devices (eg: Samsung), an image will be saved in landscape mode even if captured in portrait mode. This behavior is determined by the device's default settings. Due to platform limitations, the ES400, MC65 and MC67 do not support the color camera. Due to platform limitations, the ES400, MC65 and MC67 do not support a color camera. The imager on the MC55 with WM does not support the Fullscreen window (eg: takePicture). Parameters such as previewLeft, previewWidth, previewTop and previewHeight are supported by the device to set up a user-defined viewer window. Processor limitations of some devices may cause a low-resolution image captures to appear as a small preview with a black background when transitioning back to the application. For images captured with the camera using a Rho app, the image might initially appear black. Refresh the view to correct the problem. High-resolution settings are not recommended for low-memory devices. Image previews on tablet devices might appear stretched or shrunken.