Images in CommCare

Owned by Cory Zue
Last updated: 30 minutes ago by Krinda Wernicke

Table of Contents:

Image Best Practices

In terms of what kinds of images to use to communicate ideas to low-literate users, past research indicates a preference for life-like line drawings over pictures or super cartoonish things (though trade-offs include that photos, for example, may be easier to update.).

Images may have too much detail and be distracting, while cartoon-ish subjects may be baffling to audiences not familiar with the particular style of caricature. The use of colors and other illustrative effects to highlight the particular area of interest is also helpful (e.g. red on the dress of a black-and-white person to indicate bleeding).

When using illustrations, it is also important to maintain context (e.g. it is better to show a womb with torso, arms, and legs, rather than just a womb by itself.)

Image Sources

You can find some open-source images that you can use in your applications in these places:https://thenounproject.com/

Image Format

Images in CommCare should be formatted as 32 bit PNG files. Transparency is supported on most phones.

PNG is the recommended file format.  You can use other image formats, if supported by your phone, but the file-paths that are automatically generated in the form builder will end in "png."  

If you want to use a different format, you will need to manually change the file-paths.

Image Sizes

The size at which your images will display in CommCare is dependent upon 2 things: 1) the original size of the image file you provide, and 2) the Android device model you are using. The 2nd criteria has to do with Android device specs, and is unimportant unless you are deploying your app on multiple Android device models. If so, refer to this section for guidance on sizing your images for use on multiple device models.

If you will only be deploying your app on 1 device type, the only thing you need to consider is the size of the image file you provide. It is important for images that will appear in a form to be sized appropriately so that the entire question and options fit on a single screen without scrolling. It is also important for images that will appear in case lists or be used as menu icons not to be too big or too small. The table below provides some suggested dimensions for different types of images on specific devices (file sizes are in the format width x height in pixels). These are meant only as a guideline, and are not exact.

If you do not see your device in this table yet, or just want to a reliable way to test out different image sizes, a new process to help you do so can be found at https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143947176. If you determine image sizes that work well for a new phone model, feel free add information to the table.

On Android phones, there is also limited support for automatic resizing of images. Documentation for this feature can be found at .

Below are some free tools we have used in processing images.  No guarantee that they will work as they are third-party programs, but we have had good experiences with them.

Paint.net: Free software for editing images. Compatible on PC. 

IrfanView: Free software for re-sizing images and converting among file types.  Can also do re-sizing and conversion in bulk if you have lots of images to process at once. 

Greenshot: Free software for taking and editing screenshots.  Very useful if you want to capture images from documents, websites, or a phone emulator.

Some PDF to Word Converter: Can extract images from a PDF file.

Resize Your Image: can upload individual photos and resize them. 

Sizing Image Files

This section includes some resources for better sizing your CommCare multimedia images.

Auto-Resize Images on Android

On Android devices, users have the option for CommCare to resize images that appear in forms automatically, based upon 1 of 3 different possible criteria:

  • Full Resize - Will try to stretch or compress the image to fill all available space on the screen, without pushing other content off.

  • Horizontal Resize - Will stretch or compress the image so that it fills all available horizontal space, while maintaining its aspect ratio.

  • Half Resize - Scale the image to be half the size of what full resize would make it.

To activate this feature, navigate to the Android Settings section of your app on HQ and select which resizing functionality you would like to use.

Note that this feature is automatically disabled if you have enabled the Image Compatibility for Multiple Device Models feature (documentation here), because the 2 have unpredictable behavior when combined.

CommCare Developer Toolkit Image Sizing

The size at which your images display in CommCare depends largely upon the size of the image file you provide. To help you choose the correct file size for how you want the image to look on your device, we have released a new CommCare Developer Toolkit app, which has a utility for image sizing. To use this, follow the steps below:

STEP 0: Get the device you will be using your app on

The final size at which images display in CommCare can also vary between Android device models. If you are only deploying your device on 1 model, just make sure to use that device model for these steps. If you will be deploying your app on multiple device models, refer to the more detailed instructions available here.

Downloading the CommCare Developer Toolkit App

  1. Download the most recent toolkit release .apk file from this page (note that this is NOT a CommCare app; it is a completely separate Android app that runs on its own).

  2. Put the .apk file on the device you wish to do image sizing for, and install it (by opening the .apk file).

Downloading the CommCare Developer Toolkit App

  1. Open the developer toolkit app and select “Size Your Images”.

  2. You will see a sample image whose size you can adjust on the screen. As you adjust the size of the image, the app will update you on the exact dimensions (in pixels) of the image that you are currently viewing, so that you can adjust the size of your image file to match. Use this tool to help you decide what size to make each of your own image files.

  3. Often, you will be looking to resize an existing image, without changing its original aspect ratio. To help you do this, you can use the “Aspect Ratio Lock” button and enter the original dimensions of the image file there. This will lock the resizable image on the screen to that aspect ratio, and then you can size it up or down from there.

CommCare Developer Toolkit Image Sizing with Multiple Android Device Models

Feature Description

Starting in CommCare 2.24, a new system has been integrated to make image sizing for apps being deployed on multiple devices easier and more predictable. In the past, many users have experienced issues with the same images appearing as different sizes on different devices. Activating this system will fix that problem, by making the size at which an image appears in CommCare consistent with the size of the image file you provide, on all devices. 

Is this feature right for me?

Before getting started, it is important to understand what this feature will and will not do to your images in CommCare. This feature is specifically intended for projects that are using more than one kind of mobile device, and want to keep image sizes consistent across all of those mobile devices. If you are looking for CommCare to try to automatically resize your images, please see the Auto-Resize Images feature instead. 

If you are still unsure, consider the following to determine if this setting will be useful for your project:

  • This feature will NOT be useful to you if: Your image is appearing larger or smaller than you would like it to on a single device, and you want CommCare to size it up/down for you to fix that. If this is the problem you are experiencing, the best course of action is likely to change the size of the original image file that you are providing to CommCare. If you are looking for CommCare to size your image up/down based upon available screen space, try the auto-resize feature mentioned above.

  • This feature WILL be useful to you if: Your app is being deployed on multiple devices, and you are experiencing inconsistency with your image sizes across those different devices. In this case, users often find that the same image will show up at different sizes on those different devices, meaning that on SOME devices, an image is either too big or too small.

How to Enable this Feature

Selecting a Device

Determine the highest resolution device that your app is likely to be run on (highest resolution basically means the best quality screen, and will generally correspond to the newest/nicest/best device available, so that is a fine way to determine which device to use). If you are not yet certain what device your project will be using, just use the highest resolution / best device you have. The most important thing is just that you use the same device for all of the following steps.

Download the CommCare Developer Toolkit

  1. Download the CommCare Toolkit app from the Google Play Store (note that this is not the CommCare app, it's a separate Android app that runs on its own).

Sizing Your Image

  1. Open the Developer Toolkit App and select “Size Your Images”.

  2. You will see a sample image whose size you can adjust on the screen. As you adjust the size of the image, the app will update you on the exact dimensions (in pixels) of the image that you are currently viewing, so that you can adjust the size of your image file to match. Use this tool to help you decide what size to make each of your own image files.

  3. Often, you will be looking to resize an existing image, without changing its original aspect ratio. To help you do this, you can use the “Aspect Ratio Lock” button and enter the original dimensions of the image file there.

Determine Your Device Density

  1. Go back to the home screen of the toolkit app, and then select “About My Device”.

  2. Take note of the value listed next to “Screen Density”; you will need this in the next step.

Activate This Feature

  1. Once you have finished sizing and uploading your image files, select the gear icon in the top left corner by your application name to proceed to the Application Settings page. 

  2. Then select the 'Advanced Settings' tab. 

  3. Once on the advanced tab, select the menu options on the right hand side (the three stacked lines). Checking the "Android Settings" option from this menu will open various settings for you to configure.

  4. Find the setting entitled "Image Compatibility on Multiple Devices" and select the value in the dropdown menu that most closely matches the value you obtained for "Screen Density" in the previous step. 

  5. Make a new build of your app in order for this settings change to take effect.

  6. That’s it. Updating this setting provides CommCare with the information it needs to keep your image sizes consistent across all devices. You do NOT need to repeat this process on other devices, even if your app is going to be deployed on multiple devices; doing it on one device suffices.