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.
STEP 1: Downloading the CommCare Developer Toolkit App
Download the most recent toolkit release .apk file from this page https://github.com/dimagi/commcare-developer-toolkit/releases (note that this is NOT a CommCare app; it is a completely separate Android app that runs on its own).
Put the .apk file on the device you wish to do image sizing for, and install it (by opening the .apk file).
STEP 2: Sizing your images
Open the developer toolkit app and select “Size Your Images”.
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.
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.
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.
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
STEP 1: 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.
STEP 2: Downloading the CommCare Developer Toolkit App
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).
STEP 3: Sizing your images
Open the Developer Toolkit App and select “Size Your Images”.
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.
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.
STEP 4: Determining your device density
Go back to the home screen of the toolkit app, and then select “About My Device”.
Take note of the value listed next to “Screen Density”; you will need this in the next step.
STEP 5: Activating this feature for your app
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.
Then select the 'Advanced Settings' tab.
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.
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.
Make a new build of your app in order for this settings change to take effect.
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.