Summery

O3 does not provide a structured way to record a visual observation on a body diagram. This feature introduces an annotation field for clinical forms, allowing a clinician to select or upload a diagram, annotate it, save it as part of the form submission, and retrieve it from the patient's attachments.

Related links

• Epic: https://openmrs.atlassian.net/browse/O3-5941

• Talk thread (this implementation): O3: Draw on a body diagram — New Implementation

• Earlier requirements discussion: O3 Feature: Draw on a body diagram

• GSoC 2023 archive page: GSoC 2023: O3 Draw on a body diagram

• Requirement gathering doc for ICRC: https://docs.google.com/document/d/1RSTF9FKiLY36xys8tP0x-wqMmbhC52D78APPh1la0QI/edit?usp=sharing

Table of content

OpenMRS is a medical record system that has previously (O2) allowed the uploading and visualisation of patient conditions through diagrams. This feature has been critical in helping doctors better explain and record patient conditions. However, the OpenMRS O3 React Form Engine module lacked certain essential functionalities that could improve the user experience, which allowed clinicians to record a condition visually and explain it to the patient more clearly.

This feature brings the diagramming capability into OpenMRS O3 by allowing users to upload any diagram as an image, annotate specific areas with shapes, save and retrieve annotated diagrams, and download them as images with the annotations included.

• Upload any diagram as an image/template to the module

• Annotate areas of the diagram with shapes (circles, squares, single points, etc.)

• Save annotated diagrams for future reference

• Retrieve diagrams from a list of already saved ones

• Draw freehand shapes and annotate them with descriptive text

• Download diagrams as images with the annotations included, for sharing and printing

This could make a real impact for the community and meaningfully improve clinicians' workflows. O3 brings modern technology and architecture with improved usability, design, and user experience, but in some regions the draw-on-body feature is used heavily in day-to-day workflows. For example, the ICRC uses it to visualise body conditions caused by war injuries. Because the capability exists only in O2, those teams keep depending on it.

According to the ICRC situation, they use print body diagram sheets, draw on them by hand, photograph the paper, and upload the photo as an attachment to the form. This works because O3 already supports multiple attachments per form, but it is slow, repetitive manual effort, image quality and consistency depend on paper and a camera being available. Bringing annotation directly into O3 removes the paper step, improves efficiency, and makes the resulting records more sustainable.

A new patient arrives at the clinic with a war injury. The doctor (or clinical assistant) opens a clinical form to record the visit. At the point where a visual observation is needed, they pick a body diagram template of a full front body, full back body, arm, leg, or head and open it in the annotation editor. There, they mark where the injury is, where the bullet entered, and add short remarks about the condition of the body for future reference. They save the annotated image, continue filling in the rest of the form, and submit it. Afterwards, the annotated diagrams can be seen as images on the Attachments page in the patient chart.

Two main roles have been identified as main roles

• Clinical administrator (Form designer)

• Clinician (Doctor/Clinical Assistant)

• As a clinical administrator, I want to add an annotation field to a clinical form to capture visual observations as part of the form.

• As a clinical administrator, I want to assign a set of available diagram templates to an annotation question so that clinicians are offered only the diagrams relevant to that form.

• As a clinical administrator, I want to configure how those templates are presented to the clinician so that the form reflects the way the clinical team works.

Template presentation options

Option	Behaviour	Visual example

Option	Behaviour	Visual example
Thumbnail grid (predefined)	A fixed set of templates is displayed directly beneath the question. The clinician annotates the ones required. No additional templates can be introduced while the form is being filled.	Open Predefined templates
Dynamic selection	A set of templates is associated with the question. The clinician selects the required template on demand and annotates it.	Open Dynamic selection

• As a clinician, I want to select a body diagram template within the form and annotate it, so that I can record the location of an injury without leaving the form.

• As a clinician, I want to preview a template before annotating it so that I can confirm the correct diagram has been selected.

• As a clinician, I want to upload my own diagram when none of the provided templates are suitable in dynamic selection.

• As a clinician, I want to edit or delete an annotation before submitting the form.

• As a clinician, I want the annotated diagram to be saved with the form and to appear in the patient's attachments so that the visual observation is available to anyone reviewing the record later.

Notes after ICRC call

• As a clinician, I want to annotate and save predefined clinical image templates attached to form questions, with the option to add a description when needed, so that I can capture and explain findings visually as part of the patient's record.

  A form may contain one or more annotation questions. Each question may have a single predefined image template or multiple templates depending on the clinical context, and may optionally allow a textual description alongside the annotation.

  For example, a respiratory examination form may include a question with anterior and posterior chest diagrams for documenting auscultation findings, while another question may use a single lung lobes diagram for marking and describing the location of pulmonary findings.

• As a clinician, I want to capture a photo of a patient's real wound, annotate directly on top of that image, and save it with the form so that I can visually document wound findings as part of the patient's clinical record.

  A form may contain one or more wound photo annotation questions. For each question, I should be able to capture or upload a wound image, add annotations on top of it, and optionally include a description when needed.

  For example, during a wound assessment, I may need to take a photo of a leg ulcer, mark the wound boundary or areas of concern on the image, and add a short description of the findings before saving it with the encounter.

1. The clinician opens the clinical form.

2. The templates assigned to the annotation question are displayed as a thumbnail grid.

3. The clinician selects Annotate on the required template.

4. The annotation editor opens with that template loaded.

5. The clinician annotates the diagram and saves it.

6. The saved annotation is attached to the question, with edit and delete options available on it.

7. The clinician completes the remaining fields and submits the form.

1. The clinician opens the clinical form. No template grid is displayed beneath the question.

2. The clinician selects Add annotation under the question.

3. A modal opens listing the templates available for that question.

4. The clinician selects a template and reviews the preview.

5. The clinician annotates the diagram and saves it.

6. The saved annotation appears beneath the question, with edit and delete options available on it.

7. The clinician completes the remaining fields and submits the form.

1. From the same modal, the clinician opens the Upload tab.

2. The clinician uploads a custom diagram image.

3. The clinician annotates the uploaded diagram and saves it.

4. The clinician completes the remaining fields and submits the form.

Outcome (all flows). Once the form is submitted, the saved annotations are available as images on the Attachments page of the patient chart.

In each of the flows above, the annotation editor opens with the selected template loaded. The following tools are required:

O2 supported this capability through the Drawing Module, integrated with HTML Form Entry (HFE).

Open

Drawing module

Open

Select a template

• Each drawing is saved as a complex observation. The underlying concept is created with datatype Complex, concept class Drawing, and handler DrawingHandler.

• The module supports drawing on whole-body front/back views, hand/arm top/bottom, retinas, and other anatomical diagrams, as well as freehand upload and annotation on any image.

• A preloadResImage attribute loads a predefined background image, for example, "Full Body Lateral Female", from the module's bundled resources or an uploaded image. An admin page allows templates to be added and deleted.

• Clinicians work from physical, pre-printed body diagram sheets.

• Injuries, points of entry, and remarks are drawn on the diagram paper sheet by hand.

• A photograph is uploaded as an attachment to the relevant OpenMRS form. O3's existing support for multiple attachments per form.

• Survey of body-diagram or annotation capabilities in comparable open-source and commercial EMRs

• Waiting for the answers to this requirements gathering doc from the ICRC team.

• Selection of an external annotation library for integration with OpenMRS, including licence, maintenance status, and feature coverage

• Storage of the annotated output, and whether structured annotation data is retained alongside the rendered image.

• Definition and registration of the new rendering type for the React Form Engine integration

• Integration with the Attachments module

Open

Planned wireframe to implement the initial steps

Design link : https://claude.ai/code/artifact/dd204e03-bd10-4ce6-a274-39b2cb0cd739

See full Visual walkthrough here👇

Quick image explanation

Open

Two methods of displaying Templates

Open

Predefined method

Open

Add multiple method

Open

Select templates from the dropdown method

Open

Upload template option

Open

Set a proper name

Open

See saved annotations as Attachments

2026.08.21 - Meeting 1: OpenMRS/ICRC Check-in

Participants – Kavinda, Jayasanka, Ljubomir

Objective

• Gather the requirements from ICRC, understand current workflow with body diagrams

Summary

• I have sent the requirement gathering document to ICRC to fill ithttps://docs.google.com/document/d/1RSTF9FKiLY36xys8tP0x-wqMmbhC52D78APPh1la0QI/edit?usp=sharing

• Demonstrate the UI mockups to get ICRC input, and he accepted the overall flow as correct. https://youtu.be/cNackdcNyHc?si=HDbpW_8m1U4aAzm4

• Mentioned that they want to put templates for any part of the body to clearly show war injuries.

• They want freedom and more flexibility on this feature to have a focus on encounters.

• Mentioned the template upload capability for clinical forms.

• The current toolset is enough for drawings.

Next Things

• Make a wiki page

2026.08.26 - Meeting 2: Weekly Mentor Call

Participants – Kavinda, Jayasanka

Updates

• Show created wiki page

Summery

• Discuss to break down Epic and user stories

• OpenMRS configs

• 1st iteration is focus on implementation, not configurations

Next Things

• Send a draft use story list to review

• Prepare esm-draw app to use

• Add Annotation button PR

2026.09.02 - Meeting 3: Weekly Mentor Call

Participants – Kavinda, Jayasanka

Updates

• Take feedback on the created task list - https://docs.google.com/document/d/1OFQ4QBuwS239VfFOK3k64660pWWwQYcO-BtqMB05Dlc/edit?usp=sharing

• Bruke’s feedback understand - https://talk.openmrs.org/t/o3-draw-on-a-body-diagram-new-implementation/49754/14

Summery

• Discuss about first PR for add annotation button

• Bruke mentioned that we need to place a text box on digrams to add remarks; we discussed about it.

• Need to add a new annotation type to the form schema – https://github.com/openmrs/openmrs-contrib-json-schemas/blob/main/form.schema.json

Next Things

• PR for adding the annotation button

• PR for form-schema update

• PR for open modal with template list view and preview

2026.09.09 - Meeting 4: Weekly Mentor Call

Participants – Kavinda, Jayasanka

Updates

• Discuss the first PRs that I made – https://openmrs.atlassian.net/browse/O3-5945

  • Brief them

  • Explain their requirements

  • Understood their effectiveness

  • Got feedback for the PR

Summery

With that PR, we started talking about one special point we hadn't discussed before: the decoupled behaviour in OpenMRS using Slots and Extensions.

My responsibility is to build the components for the Annotation and Form Selection UI.

The form engine, however, is responsible for keeping the form state, defining the right component and its state, and calling the functions that handle the components' behavior.

OpenMRS specifically maintains a slot-extension mechanism, which allows them to replace things with different modules. So the idea is to give the handling responsibility/behavior to the Draw module, so that in the future it can be replaced with another module. The form engine keeps the form state.

As our last decision, we have two methods to show the templates:

1. Show predefined templates (there can be one or more for quick access, and this will be used in most cases). For example, if there is a question like "front body," there will be a template for the front body. In some cases, there can be several templates to capture multiple inputs.

2. The second method offers a free-selection approach. In this case, there is only an "Add Annotation" button, which opens a modal to select a list of templates to annotate. We plan to pass the template list as module configs.

So the end goal is that in the future, any user can plug in their own module here.

One of the most important things we discussed was how to make the tradeoffs. Jaye gave me the opportunity to navigate through it and think about how much flexibility we need — whether it's required, whether it has value, and what it would look like if we gave that flexibility. We had two options:

1. Every render is handled by the module — in this way, the module owns both the behavior and the contract (the contract meaning how we show the buttons, template selection, and everything else). The form engine owns only the state.

2. In the second method, we planned it like this: the form engine shows how the components should be displayed, and the module is only responsible for handling the behavior. So the form engine will show the thumbnails and buttons, which call the relevant functions in the relevant module. I chose this approach because it means the module only owns the behavior part.

Most importantly, we planned to go with two types for the annotations:

• FreeformAnnotation

• PredefinedAnnotation

Open

Next things

• Show thumbnails

• Call Drawer module from templates