Menu

BVI IMAGE API GUIDE for developers

The API allows businesses to incorporate body composition analysis into their smartphone apps. The body composition section of an app which uses the API would work as follows:

  1. A user enters some basic details into the app: gender, age, height, weight and activity level, if these are not already known.
  2. The user, wearing close-fitting clothing, no shoes, takes two selfie type photos in a mirror.
  3. They then identify the size and location of their waist and hips in the images.
  4. The app then calls the BVI Image API in order to receive the results of body composition calculations. Sending photos to the API is optional.
  5. The results returned include BMI, Total Body Fat (%), and Visceral Fat (litres).
  6. The Total Body Fat and Visceral Fat also have a zone indication, i.e. (‘very low', 'low', 'normal', 'high', 'very high’) to help users understand their results. The BVI Image SDK includes a set of overlay images to use when photos are taken. These images match the BMI categories.

The SDK also includes some textual information about the 5 body fat zones. This information can be used to enhance the user experience. The SDK also contains a “powered by BVI” logo that should be used when the body composition results are displayed. The BVI Image API is delivered as a RESTful web service hosted on Amazon Web Services. The documentation for the API calls is provided by a link on bodyvolume.com.

 

API DEMO app

Select Research has built a demonstration app which provides one example of a user interface design and demonstrates live operation of the BVI Image API. This app allows potential customers of Select Research to directly experience the system in operation.

If you are interested in trying the app, please contact api@select-research.com. Following some discussions we can provide you access to an Apple device which has the app pre-installed so that you can test it thoroughly. The app is not available via the App Store or via TestFlight. Select Research is also making available a demonstration video, which you can view on the API pages at bodyvolume.com. Also, below is a set of screenshots from the demonstration app:

Photo taking

When taking a full-length selfie in a mirror attached to a wall or wardrobe, the smartphone will be tilted forwards by approximately 20 degrees. To improve accuracy, the developer should incorporate tilt detection into their app and record the tilt value. This will be sent as part of the BVI Image API call. The API call also includes a boolean variable to indicate whether the mirror was vertical (i.e. attached to a wall or wardrobe) or not. Examples of non-vertical mirrors include tilted freestanding mirrors, or a mirror leaned up against a wall. In these instances, the tilt value from the device will not be useful in improving the calculations, so the specific device tilt will be disregarded and a 20 degree effective tilt value assumed. You own custom app should use the standard wide angle rear camera, without any digital zoom, in portrait orientation, with the flash disabled. The full frame camera view should be a 3:4 aspect ratio.

By knowing the gender of the person measuring themselves, and having calculated their BMI from the data entered, an appropriate dotted overlay alignment mask should be presented over the live camera view. This mask makes it clear how the user should position themselves in the photo. The BVI Image SDK contains a set of overlays that can be used for this purpose. An alignment mask must be overlaid over the entire live camera view. The screen size of various devices may vary but the developer should ensure that the alignment mask covers the entire camera view, and that the full height of the view is displayed to the user. Below are examples of the front and side mask. These outlines have been distorted to match the appearance seen in a mirror.

 

Slider positions

Once the photos are taken, 4 positions (co-ordinates) must be identified on each image - the start and end of a horizontal line describing the waist, and the start and end of a horizontal line describing the hips. You may design any style of slider system that you prefer, so long as the data sent to the server truly represents the end-users waist and hip locations. The hips should normally be measured at the widest part and the waist at the narrowest part usually just above the navel. See photo below for guidance.

 

 

Once the photos are taken, 4 positions (co-ordinates) must be identified on each image - the start and end of a horizontal line describing the waist, and the start and end of a horizontal line describing the hips. You may design any style of slider system that you prefer, so long as the data sent to the server truly represents the end-user’s waist and hip locations. The hips should normally be measured at the widest part and the waist at the narrowest part usually just above the navel. See photo below for guidance.

 

 

API Call Inputs

The API will use metric units only. You may wish to translate to imperial units if required for the purposes of an improved user experience. The following table is provided as a guide, and the actual API documentation takes precedence.

The range limits shown in this table should be applied at the user interface when data is entered by the user. Exceeding these limits may generate an out of range error response from the web service.

Each photo should be accompanied by a tilt value derived from the device's accelerometer. The tilt is measured in degrees where tilting the device forwards (i.e. pointing it towards the ground slightly) generates a positive tilt value.

When the photos are taken, the device will be tilted at approximately 20 degrees when the image of the person is aligned with the overlay. If the mirror is not vertical, the web service will assume a tilt of 20 degrees.

API Call - Outputs

The results returned by the API will be as follows

 

Below is an example of the image returned from the web service, if images were submitted for processing.



The web service will process and return a composite image. It does not store images sent to it. To enhance privacy, you may choose to send no images, or to send anonymised or abstracted versions of the photos, depending on how you wish to manage your users.

Documentation for Developers

For further information on integrating the BVI API please see the documentation below.

BVI API Documentation for Developers 

BVI Pro

We are busy improving the user experience on BVI Pro and will be back on the App Store soon.

For further information please email contact@bvi-america.com 

 

Returning to the App Store Soon!