Camera

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 for important information about using this API in JavaScript

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby

Methods

capture

(CallBackHandler callback)

Capture the image and save it to a file.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

status : STRING

Whether or not the image was successfully captured. The returned string will be one of ‘ok’ or ‘error’.
imageUri : STRING

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.
imageHeight : INTEGER

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.
imageWidth : INTEGER

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.
imageFormat : STRING

The format in which the image was captured, either ‘png’ or ‘jpg’.
message : STRING

If the returned status is ‘error’ then this field will contain more information on the error.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.capture(CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.capture(CallBackHandler callback)
- Ruby: Rho::Camera.capture(CallBackHandler callback)

choosePicture

(HASH propertyMap, CallBackHandler callback)

Choose a picture from the album.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyMap : HASH Optional

                      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 UWP 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'

Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section

Not providing properties to this function will use the Camera’s default properties, or those previously set on the Camera instance.

callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

status : STRING

Whether or not the image was successfully chosen from the gallery. The returned string will be one of ‘ok’, ‘cancel’ or ‘error’.
imageUri : STRING

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.
Platforms:Android, WM, CE, iOS, UWP
imageHeight : INTEGER

The height of the image.
imageWidth : INTEGER

The width of the image.
imageFormat : STRING

The format of the image, either ‘png’ or ‘jpg’.
message : STRING

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.
image_uri : STRING

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.
Platforms:Android, WM, CE, iOS, UWP
image_height : INTEGER

It is recommended to use imageHeight in preference to this parameter.
image_width : INTEGER

It is recommended to use imageWidth in preference to this parameter.
image_format : STRING

It is recommended to use imageFormat in preference to this parameter.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Camera.choosePicture(HASH propertyMap, CallBackHandler callback)
- Ruby: Rho::Camera.choosePicture(HASH propertyMap, CallBackHandler callback)

copyImageToDeviceGallery

(STRING pathToImage)

Replaces: save_image_to_device_gallery

Save an image to the device gallery.

JavaScript Ruby Android iphone, ipod touch, ipad

Parameters

pathToImage : STRING

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).

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Camera.copyImageToDeviceGallery(STRING pathToImage)
- Ruby: Rho::Camera.copyImageToDeviceGallery(STRING pathToImage)

enumerate

(CallBackHandler callback)

Returns the cameras present on your device, allowing you to access your device’s front or back camera.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: ARRAY

cameraArray : SELF_INSTANCE: Rho::Camera

Synchronous Return:

ARRAY :
Array of objects.
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- cameraArray : SELF_INSTANCE: Rho::Camera

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Camera.enumerate(CallBackHandler callback)
- Ruby: Rho::Camera.enumerate(CallBackHandler callback)

getAllProperties

(CallBackHandler callback)

This method will return all of object/value pairs for the propertyNames of the API class.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

: STRING

Synchronous Return:

HASH :
Map of all available properties
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- : STRING

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getAllProperties(CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.getAllProperties(CallBackHandler callback)
- Ruby: Rho::Camera.getAllProperties(CallBackHandler callback)

getCameraByType

(STRING cameraType, CallBackHandler callback)

Returns the camera of requested type if that camera exist - else return nil.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

cameraType : STRING

CameraType: ‘back’ or ‘front’ in the case of Android, iOS and UWP and ‘color’ or ‘imager’ in the case of WM, CE devices
callback : CallBackHandler Optional

Async Callback Returning Parameters: SELF_INSTANCE

Synchronous Return:

SELF_INSTANCE :
Camera with requested type or nil if not requested type does not exist. Refer example section for more details.
: this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Camera.getCameraByType(STRING cameraType, CallBackHandler callback)
- Ruby: Rho::Camera.getCameraByType(STRING cameraType, CallBackHandler callback)

getDefault

()

This method will return an object that represents the default instance of the API Class. For example Camera.getDefault will return a Camera object that represents the default camera.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Synchronous Return:

SELF_INSTANCE :
Default object of Module.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Camera.getDefault()
- Ruby: Rho::Camera.getDefault()

getProperties

(ARRAY arrayofNames, CallBackHandler callback)

This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

arrayofNames : ARRAY

List of properties I want to know about

Object : STRING

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

: STRING

Synchronous Return:

HASH :
Map of properties I want to know about
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- : STRING

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getProperties(ARRAY arrayofNames, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.getProperties(ARRAY arrayofNames, CallBackHandler callback)
- Ruby: Rho::Camera.getProperties(ARRAY arrayofNames, CallBackHandler callback)

getProperty

(STRING propertyName, CallBackHandler callback)

This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyName : STRING

The property to return info about.
callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

STRING :
The property to return info about.
: this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getProperty(STRING propertyName, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.getProperty(STRING propertyName, CallBackHandler callback)
- Ruby: Rho::Camera.getProperty(STRING propertyName, CallBackHandler callback)

hidePreview

()

Hides the preview opened by using showPreview.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.hidePreview()
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.hidePreview()
- Ruby: Rho::Camera.hidePreview()

setDefault

(SELF_INSTANCE: Rho::Camera defaultInstance)

This method allows you to set the attributes of the default object instance by passing in an object of the same class.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

defaultInstance : SELF_INSTANCE: Rho::Camera

An instance object that is of the same class.

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Camera.setDefault(SELF_INSTANCE: Rho::Camera defaultInstance)
- Ruby: Rho::Camera.setDefault(SELF_INSTANCE: Rho::Camera defaultInstance)

setProperties

(HASH propertyMap)

This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyMap : HASH

Map of properties I want to set

Object : STRING

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.setProperties(HASH propertyMap)
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.setProperties(HASH propertyMap)
- Ruby: Rho::Camera.setProperties(HASH propertyMap)

setProperty

(STRING propertyName, STRING propertyValue)

This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyName : STRING

The one property name that I want to set
propertyValue : STRING

The one property value that I want to set

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.setProperty(STRING propertyName, STRING propertyValue)
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.setProperty(STRING propertyName, STRING propertyValue)
- Ruby: Rho::Camera.setProperty(STRING propertyName, STRING propertyValue)

showPreview

(HASH propertyMap)

Shows the preview in user configurable viewer window.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyMap : HASH Optional

Provide a set of properties to configure the camera.
Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section
Not providing properties to this function will use the Camera’s default properties, or those previously set on the Camera instance.

Synchronous Return:

Void

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.showPreview(HASH propertyMap)
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.showPreview(HASH propertyMap)
- Ruby: Rho::Camera.showPreview(HASH propertyMap)

takePicture

(HASH propertyMap, CallBackHandler callback)

              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.
              When you use 'outputFormat' is 'image' captured image will be saved into file and you should control this file by self - remove it if you do not use it anymore etc.
              On UWP,wm when 'outputFormat' is 'image' then imageUri/image_uri shall have only Image name with \ sign, on UWP 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
                            Rho::RhoApplication.expandDatabaseBlobFilePath(x.image_uri)

              ##### JavaScript
              :::js
              Rho.RhoApplication.expandDatabaseBlobFilePath(x.image_uri)

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyMap : HASH Optional

Provide a set of properties to configure the camera, for example to specify the flashMode or compressionFormat.
Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section
Not providing properties to this function will use the Camera’s default properties, or those previously set on the Camera instance.
callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

status : STRING

Whether or not the image was successfully captured. The returned string will be one of ‘ok’, ‘cancel’ or ‘error’.
Platforms:Android, WM, CE, iOS, UWP
imageUri : STRING

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.
Platforms:Android, WM, CE, iOS, UWP
imageHeight : INTEGER

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.
Platforms:Android, WM, CE, iOS, UWP
imageWidth : INTEGER

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.
Platforms:Android, WM, CE, iOS, UWP
imageFormat : STRING

The format in which the image was captured, either ‘png’ or ‘jpg’.
Platforms:Android, WM, CE, iOS
message : STRING

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.
Platforms:Android, WM, CE, iOS, UWP
image_uri : STRING

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.
Platforms:Android, WM, CE, iOS, UWP
image_height : INTEGER

It is recommended to use imageHeight in preference to this parameter.
Platforms:Android, WM, CE, iOS, WP8
image_width : INTEGER

It is recommended to use imageWidth in preference to this parameter.
Platforms:Android, WM, CE, iOS, UWP
image_format : STRING

It is recommended to use imageFormat in preference to this parameter.
Platforms:Android, WM, CE, iOS

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.takePicture(HASH propertyMap, CallBackHandler callback)
Default Instance: This method can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.takePicture(HASH propertyMap, CallBackHandler callback)
- Ruby: Rho::Camera.takePicture(HASH propertyMap, CallBackHandler callback)

Properties

aimMode

: STRING

Description
Access

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_…

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.aimMode
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.aimMode
- Ruby: Rho::Camera.aimMode

cameraType

: STRING Read Only

Description
Access

Replaces:camera_type

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_…

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.cameraType
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.cameraType
- Ruby: Rho::Camera.cameraType

captureSound

: STRING

Description
Access

Path to a sound file resident on the device which will be played when the image is captured.

JavaScript Ruby Android Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.captureSound
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.captureSound
- Ruby: Rho::Camera.captureSound

colorModel

: STRING

Replaces: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_…

JavaScript Ruby Android iphone, ipod touch, ipad

Default: rgb

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.colorModel
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.colorModel
- Ruby: Rho::Camera.colorModel

compressionFormat

: STRING

Replaces:format

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_…

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Default: jpg

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.compressionFormat
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.compressionFormat
- Ruby: Rho::Camera.compressionFormat

desiredHeight

: INTEGER

Description
Access

Replaces:desired_height

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.desiredHeight
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.desiredHeight
- Ruby: Rho::Camera.desiredHeight

desiredWidth

: INTEGER

Description
Access

Replaces:desired_width

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.desiredWidth
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.desiredWidth
- Ruby: Rho::Camera.desiredWidth

enableEditing

: BOOLEAN

Replaces:enable_editing

Enables post photo capture image customizing; image will captured reduced to screen size (not full size of camera sensor).

JavaScript Ruby iphone, ipod touch, ipad

Default: true

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.enableEditing
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.enableEditing
- Ruby: Rho::Camera.enableEditing

fileName

: STRING

Description
Access

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 UWP, only filename can be changed, by default the path shall be under picture=>CameraRoll

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.fileName
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.fileName
- Ruby: Rho::Camera.fileName

flashMode

: STRING

Description
Access

Replaces:flash_mode

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_…

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.flashMode
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.flashMode
- Ruby: Rho::Camera.flashMode

maxHeight

: INTEGER Read Only

Description
Access

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.maxHeight
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.maxHeight
- Ruby: Rho::Camera.maxHeight

maxWidth

: INTEGER Read Only

Description
Access

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.maxWidth
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.maxWidth
- Ruby: Rho::Camera.maxWidth

outputFormat

: STRING

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_…

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Default: image

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.outputFormat
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.outputFormat
- Ruby: Rho::Camera.outputFormat

previewHeight

: INTEGER

Description
Access

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.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.previewHeight
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.previewHeight
- Ruby: Rho::Camera.previewHeight

previewLeft

: INTEGER

Description
Access

Replaces:left

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.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.previewLeft
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.previewLeft
- Ruby: Rho::Camera.previewLeft

previewTop

: INTEGER

Description
Access

Replaces:top

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.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.previewTop
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.previewTop
- Ruby: Rho::Camera.previewTop

previewWidth

: INTEGER

Description
Access

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.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.previewWidth
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.previewWidth
- Ruby: Rho::Camera.previewWidth

saveToDeviceGallery

: BOOLEAN

Replaces:save_to_shared_gallery

If true, the picture you take will be added to the device photo gallery.

JavaScript Ruby Android iphone, ipod touch, ipad

Default: false

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.saveToDeviceGallery
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.saveToDeviceGallery
- Ruby: Rho::Camera.saveToDeviceGallery

supportedSizeList

: ARRAY Read Only

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Object : HASH

width : INTEGER
height : INTEGER

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.supportedSizeList
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.supportedSizeList
- Ruby: Rho::Camera.supportedSizeList

useRealBitmapResize

: BOOLEAN

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.

JavaScript Ruby Android

Default: true

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.useRealBitmapResize
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.useRealBitmapResize
- Ruby: Rho::Camera.useRealBitmapResize

useRotationBitmapByEXIF

: BOOLEAN

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.

JavaScript Ruby Android

Default: true

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.useRotationBitmapByEXIF
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.useRotationBitmapByEXIF
- Ruby: Rho::Camera.useRotationBitmapByEXIF

useSystemViewfinder

: BOOLEAN

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).

JavaScript Ruby Android

Default: true

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.useSystemViewfinder
Default Instance: This property can be accessed via the default instance object of this class.
- JavaScript: Rho.Camera.useSystemViewfinder
- Ruby: Rho::Camera.useSystemViewfinder

Constants

STATUS_OK: Status constant.
STATUS_ERROR: Status constant.
STATUS_CANCELLED: Status constant.
CAMERA_TYPE_BACK: Back camera. This is not supported in WM/CE devices.
CAMERA_TYPE_FRONT: Front camera. This is not supported in WM/CE devices.
CAMERA_TYPE_IMAGER: Camera is an imager. This is supported only in WM/CE devices.
CAMERA_TYPE_COLOR: Camera is color camera. This is supported only in WM/CE devices.
COMPRESSION_FORMAT_JPG: JPG compression.
COMPRESSION_FORMAT_PNG: PNG compression.
OUTPUT_FORMAT_IMAGE: 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
OUTPUT_FORMAT_DATAURI: 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.
OUTPUT_FORMAT_IMAGE_PATH: 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 10.
COLOR_MODEL_RGB: A colour image is captured.
COLOR_MODEL_GRAYSCALE: A grayscale image is captured.
FLASH_ON: Flash will be used.
FLASH_OFF: Flash will not be used.
FLASH_AUTO: Flash will be used if lighting conditions deem it necessary. This is not supported in WM/CE devices.
FLASH_RED_EYE: Flash with red eye reduction is used. This is supported only in Android devices.
FLASH_TORCH: The flash is turned on in torch mode. This is supported only in Android devices.
AIM_ON: Switches the imager’s aim to ON
AIM_OFF: Switches the imager’s aim to OFF

Examples

Take picture with default camera

Take an image with as little code as possible, using all default values.

JavaScript
Ruby

function take_picture_with_default_camera() {
  // Capture an image from the default camera on the device, using the default image settings
  Rho.Camera.takePicture({}, picture_taken_callback);
}

function picture_taken_callback(params) {
  // Did we receive an image?
  if (params["status"]=="ok") {
    // Assuming we have an <img id="#captured_image"> tag, we will be able to see the image that was just captured
    $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"]));
  }
}

def take_picture_with_default_camera
  # Capture an image from the default camera on the device, using the default image settings
  Rho::Camera.takePicture({}, :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

Choose which camera to use when taking images

On devices with more than one camera, you can select which camera to use for taking pictures.

JavaScript
Ruby

<div id="camera_list">
</div>


var cameras = [];

function choose_camera() {
  // get all available cameras
  cameras = Rho.Camera.enumerate();

  // build an HTML list
  var cameraList = "<ul>";

  for (var cameraIndex=0; cameraIndex<cameras.length; cameraIndex++) {
    var camera = cameras[cameraIndex];
    // Create a link for each camera with an onclick handler
    cameraList = cameraList +'<li><a href="#" class="take_picture_with_selected_camera" onclick="take_picture_with_camera('+cameraIndex+')">'+camera.cameraType+'</a></li>';
  }

  cameraList = cameraList+"</ul>";

  // 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);
}

# controller.rb
def choose_camera
  $cameras = Rho::Camera.enumerate
  render
end

def take_picture_using_chosen_camera
  camera = $cameras[@params["cameraIndex"].to_i]
  camera.takePicture({}, url_for(:action => :picture_taken_callback))
end


# choose_camera.erb
<ul data-role="listview">
  <% $cameras.each_with_index do |camera, index| %>
    <li><a href="<%= url_for(:action => :take_picture_using_chosen_camera, :query => {:camera_index => index}) %>"><%= camera.cameraType %></li>
  <% end %>
</ul>

Saving a picture to the device's gallery

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.

JavaScript
Ruby

function take_picture_and_save_it_to_gallery() {
  Rho.Camera.choosePicture({}, picture_taken_callback_save_to_gallery);
}

function picture_taken_callback_save_to_gallery(params) {
  if (params["status"]=="ok") {
    Rho.Camera.copyImageToDeviceGallery(Rho.Application.expandDatabaseBlobFilePath(params["imageUri"]));

    alert("Image saved to gallery");
  }
}

def take_picture_and_save_it_to_gallery
  Rho::Camera.choosePicture({}, url_for(:action => :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

Control image properties

You can tweak multiple options to get an image exactly as you need it

JavaScript
Ruby

function control_image_properties() {
  // Instead of accepting the defaults, let's set some properties to our liking

  // We will ask for a PNG file...
  Rho.Camera.compressionFormat = "png";

  // ...a particular image size...
  Rho.Camera.desiredWidth = 1024;
  Rho.Camera.desiredHeight = 768;

  // ...and force the flash to be used
  Rho.Camera.flashMode = "on";

  // Now, take the picture
  Rho.Camera.takePicture({}, picture_taken_callback);
}

function picture_taken_callback(params) {
  // Did we receive an image?
  if (params["status"]=="ok") {
    // show it in our <img id="captured_image"> tag
    $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"]));
  }

}

def control_image_properties
  # Instead of accepting the defaults, let's set some properties to our liking

  # We will ask for a PNG file...
  Rho::Camera.compressionFormat = "png"

  # ...a particular image size...
  Rho::Camera.desiredWidth = 1024
  Rho::Camera.desiredHeight = 768

  # ...and force the flash to be used
  Rho::Camera.flashMode = "on"

  # Now, take the picture
  Rho::Camera.takePicture({}, :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

Determine camera capabilities

You can get all available camera properties in a single call.

JavaScript
Ruby

function determine_camera_capabilities() {
  var capabilitiesList = "<ul>";

  // 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+="<li>"+capability+": "+capabilities[capability]+"</li>";
  }

  capabilitiesList += "</ul>";

  // ... and show it
  $("#camera_capabilities").html(capabilitiesList);
}

# controller.rb

def determine_camera_capabilities
  # Get all camera properties
  @properties = Rho::Camera.getAllProperties
  render
end

# determine_camera_capabilities.erb
    <ul data-role="listview">

    <% @properties.each_pair do |name,value| %>
      <li><%= name %> : <%= value %></li>
    <% end %>

    </ul>

Select picture from device gallery

Apart from taking new pictures, the Camera API also lets you access existing images on the device’s gallery.

JavaScript
Ruby

function select_picture_from_gallery() {
  Rho.Camera.choose_picture({}, picture_taken_callback);
}

function picture_taken_callback(params) {
  // Did we receive an image?
  if (params["status"]=="ok") {
    // Show it in an <img> tag
    $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"]));
  }
}

def select_picture_from_gallery
  Rho::Camera.choosePicture({}, url_for(:action => :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

Getting a camera instance by cameraType

Camera API also lets you access camera instance by cameraType.

JavaScript

//get the instance by cameraType and takePicture using that instance
function get_color_camera_instance() {
  var camInst = Rho.Camera.getCameraByType('color');
  camInst.takePicture({'outputFormat':'image'}, my_callback);
}

Getting the list of resolutions supported by the camera

Camera resolution is hardware specific. Camera API supports getting the supported resolutions of a camera instance.

JavaScript

function getsupporteSizeList()
{
var instArray = Rho.Camera.enumerate();
var reslnArray = instArray[0].supportedSizeList;
alert(reslnArray[0].width);
alert(reslnArray[0].height);
alert(reslnArray[1].width);
alert(reslnArray[1].height);
}

Transfering an image to HTTP server

This example demonstrate how user can transfer an image to http server. This will be useful when application is running on a remote server.

JavaScript

//enumerate the available cameras on the device
var camArray = EB.Camera.enumerate();

//below is the callback fired by network api after image upload to the server is completed
var upload_file_callback = function (args){
        status = args['status'];
        //a status ok indicates image transferred successfully
        alert(status);
       }

//below is the camera call back fired after takePicture is called
var camera_callbackFunc = function(cbData){ 
  alert(cbData.imageUri); 
  //set the upload file properties; Refer network module for more details
  var uploadfileProps = {
           url: 'http://10.233.82.51:8081/upload_image_file',
          //authType: "basic",
          //authUser: "admin",
          //authPassword: "password",
          filename: cbData.imageUri,
          body: "uploading file",
          fileContentType: "image/jpeg"
        };
   
   //below is the network module API used for uploading images when camera fire the callback
   EB.Network.uploadFile(uploadfileProps, upload_file_callback);      
 };
 
 //below is the test function which is used for capturing an image with outputFormat set as imagePath
function Test_image_transfer1()
{ 
  //invoke takePicture API with outputFormat as imagePath and set the callback method
  camArray[0].takePicture({'fileName' : '/Application/Test/myImagename', 'outputFormat': 'imagePath'}, camera_callbackFunc);
}
 //below is the test function which is used for choosing a picture from device with outputFormat set as imagePath
function Test_image_transfer2()
{ 
  //invoke choosePicture API with outputFormat as imagePath and set the callback method
  EB.Camera.choosePicture({'outputFormat': 'image'}, camera_callbackFunc);
}

Dispalying an image using image uri.

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’

JavaScript

//enumerate the available cameras on the device
var camArray = EB.Camera.enumerate();



//below is the camera call back fired after takePicture is called
var camera_callbackFunc = function(cbData){ 

  //uri will have relative path info only
  //user has to form the absolute local server path as shown below
  uri = 'http://localhost:'+EB.System.localServerPort + cbData.imageUri;
  //set the image uri to the image element
  document.getElementById('imageUri').src = uri ;
  
 };
 
 //below is the test function which is used for capturing an image with outputFormat set as image
function Test_image_uri()
{ 
  //invoke takePicture API with outputFormat as image and set the callback method
  camArray[0].takePicture({'outputFormat': 'image'}, camera_callbackFunc);
}

Remarks

SD Card Access

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.

Camera Preview

Despite a user-selected full screen mode, preview rendering size will be overridden by the driver on some WM/CE devices.

DataUri

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.

ImageUri

Image Uri display is dependent on browser capability.

GetSupportedProperties in UWP

UWP does not support getSupportedProperties or SetSupportedProperties.

colorModel as Grayscale in Android

Grayscale is supported only in the front camera of Android consumer devices.

Invalid/Null values for properties in Android and iOS

Only valid and non-empty values for properties are supported in Android and iOS.

Ruby Support

Due to platform limitations, imager and color camera are not supported in ruby applications for CE5 and CE6 devices.

Camera in Suspend mode

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.

Image saving after taking picture

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.

WM/CE devices lacking support

Due to platform limitations, the ES400, MC65 and MC67 do not support the color camera.

takePicture resolution issue on low-memory devices with WM

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.

takePicture resolution issue on low-memory devices with WM

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.

Android KitKat gallery displays black image

For images captured with the camera using a Rho app, the image might initially appear black. Refresh the view to correct the problem.

Android preview

High-resolution settings are not recommended for low-memory devices. Image previews on tablet devices might appear stretched or shrunken.

Camera

Methods - Class

Methods - Instance

Instance Properties

Enabling the API

JavaScript Usage

Ruby Usage

Methods

Properties

Constants

Examples

Remarks