Click here to Skip to main content
15,304,433 members
Articles / Desktop Programming / WPF
Posted 12 Sep 2007


188 bookmarked

Annotating an Image in WPF

Rate me:
Please Sign up or sign in to vote.
4.89/5 (44 votes)
12 Sep 2007CPOL4 min read
Demonstrates how to add text annotations to an Image element
Image 1


This article shows how to create text annotations over an image, in a WPF application. The technique involves rendering a custom control in the adorner layer of an Image element, allowing for in-place editing of annotations. The classes used in the demo application can be easily and freely used in other applications to achieve the same functionality.


When you read the newspaper and scribble a thought on the page, you are creating an annotation. The term "annotation" refers to a note which describes or explains part of another document. The Windows Presentation Foundation has built-in support for document annotations, as described here. It does not, however, provide out-of-the-box support for annotating images.

A while back I wrote a blog post about how to annotate an Image element which happens to reside in a Viewbox. This article takes that idea and generalizes it so that any Image can be annotated, not just one contained within a Viewbox. Another improvement seen in this article's demo application is that the annotations are created "in-place", as opposed to typing the annotation text in a TextBox somewhere else in the user interface.

The demo app

This article is accompanied by a demo application, available for download at the top of this page. The demo app allows you to create annotations on two images. It contains explanatory text about how to create, modify, and delete annotations.

Here is a screenshot of the demo application, after a few annotations have been created:

Image 2

Notice the location of the various annotations, relative to entities in the picture. After the Window is made smaller, you will see that the annotations remain "pinned" to those entities:

Image 3

Even though the dimensions of the Image element have changed, the annotations remain in the same meaningful locations over the picture. This is an important aspect of image annotations, because the location of an annotation is just as meaningful as its text.

The demo app lets the user delete annotations in several ways. If an annotation loses input focus and has no text, it is automatically deleted. Also, aside from the glaringly obvious 'Delete Annotations' button seen above, you can also delete an annotation by right-clicking on it, to pull up a context menu. For example:

Image 4


The demo app is not a "complete" solution. It does not provide any means of persisting annotations across runs of the application. I did not write annotation persistence code because there are so many different ways that this functionality might be used, that writing my own implementation seemed like a shot in the dark. I did, however, try to write the classes in such a way that it will be straightforward to implement saving and loading of annotations.

The demo app also does not provide any fancy UI features like drag-drop of annotations. That might be a useful feature, but I wanted to keep this simple. Drag-drop in WPF is pretty well documented on the Web, so if you need to add that feature you should be able to find some good reference material out there.

How it works

There are four main participants involved, as seen below:

Image 5

The ImageAnnotationControl is what you actually see on the screen which displays, and allows you to edit, annotations. ImageAnnotationControl is a ContentControl which exposes one interesting public dependency property, called IsInEditMode. When that property is true, a DataTemplate is applied to the ContentTemplate property which renders the annotation text in a TextBox. When IsInEditMode is false, the annotation text is rendered in a TextBlock. The complete XAML for ImageAnnotationControl is seen below:

    <!--<span class="code-comment"> The template used to create a TextBox 
         for the user to edit an annotation. --></span>
    <DataTemplate x:Key="EditModeTemplate">
        Style="{DynamicResource STYLE_AnnotationEditor}"

    <!--<span class="code-comment"> The template used to create a TextBlock 
         for the user to read an annotation. --></span>
    <DataTemplate x:Key="DisplayModeTemplate">
          Style="{DynamicResource STYLE_Annotation}"
          Text="{Binding ElementName=mainControl, Path=Content}"
                  <Image Source="delete.ico" />

    <Style TargetType="{x:Type local:ImageAnnotationControl}">
        <!--<span class="code-comment"> Applies the 'edit mode' template 
             to the Content property. --></span>
        <Trigger Property="IsInEditMode" Value="True">
            Value="{StaticResource EditModeTemplate}" 

        <!--<span class="code-comment"> Applies the 'display mode' template 
             to the Content property. --></span>
        <Trigger Property="IsInEditMode" Value="False">
            Value="{StaticResource DisplayModeTemplate}" 

ImageAnnotationAdorner is an adorner which is responsible for hosting an instance of ImageAnnotationControl. It is added to the adorner layer of the Image being annotated. ImageAnnotationAdorner is created and positioned by the ImageAnnotation class. That class has no visual representation, but simply serves as a handle to an annotation for the consumer (i.e. the demo app's main Window).

When an ImageAnnotation is created, it installs an adorner in the annotated Image's adorner layer, as seen below:

void InstallAdorner()
    if (_isDeleted)

    _adornerLayer = AdornerLayer.GetAdornerLayer(_image);


When the Image element is resized and an annotation must be moved to its new location, these methods in ImageAnnotation are invoked:

void OnImageSizeChanged(object sender, SizeChangedEventArgs e)
    Point newLocation = this.CalculateEquivalentTextLocation();

Point CalculateEquivalentTextLocation()
    double x = _image.RenderSize.Width * _horizPercent;
    double y = _image.RenderSize.Height * _vertPercent;
    return new Point(x, y);

The _horizPercent and _vertPercent fields represent the relative location of an annotation over an picture. Those values are calculated in the ImageAnnotation constructor, as seen below:

private ImageAnnotation(
 Point textLocation, Image image, 
 Style annontationStyle, Style annotationEditorStyle)
    if (image == null)
        throw new ArgumentNullException("image");

    _image = image;

    Size imageSize = _image.RenderSize;
    if (imageSize.Height == 0 || imageSize.Width == 0)
        throw new ArgumentException("image has invalid dimensions");

    // Determine the relative location of the TextBlock.
    _horizPercent = textLocation.X / imageSize.Width;
    _vertPercent = textLocation.Y / imageSize.Height;

    // Create the adorner which displays the annotation.
    _adorner = new ImageAnnotationAdorner(


The Window in the demo app asks ImageAnnotation to create instances of itself when the user clicks on an Image. In addition to informing the annotation where it should exist over the Image, it also specifies two Styles for the ImageAnnotationControl, as seen below:

void image_MouseLeftButtonDown(object sender, MouseButtonEventArgs e)
    Image image = sender as Image;

    // Get the location of the mouse cursor relative to the Image. Offset the
    // location a bit so that the annotation placement feels more natural.
    Point textLocation = e.GetPosition(image);
    textLocation.Offset(-4, -4);

    // Get the Style applied to the annotation's TextBlock.
    Style annotationStyle = base.FindResource("AnnotationStyle") as Style;

    // Get the Style applied to the annotations's TextBox.
    Style annotationEdtiorStyle =
       base.FindResource("AnnotationEditorStyle") as Style;

    // Create an annotationwhere the mouse cursor is located.
    ImageAnnotation imgAnn = ImageAnnotation.Create(


Those two Style objects allow the annotation consumer to specify how annotations should be rendered, both when in edit mode and display mode. The demo app's Styles, which exist in the main Window's resources, are seen below:

<!--<span class="code-comment"> This is the Style applied to the TextBlock within 
     an ImageAnnotationControl. --></span>
<Style x:Key="AnnotationStyle" TargetType="TextBlock">
  <Setter Property="Background" Value="#AAFFFFFF" />
  <Setter Property="FontWeight" Value="Bold" />      
    <Trigger Property="IsMouseOver" Value="True">
      <Setter Property="Background" Value="#CCFFFFFF" />

<!--<span class="code-comment"> This is the Style applied to the TextBox within 
     an ImageAnnotationControl. --></span>
<Style x:Key="AnnotationEditorStyle" TargetType="TextBox">
  <Setter Property="Background" Value="#FFFFFFFF" />
  <Setter Property="BorderThickness" Value="0" />
  <Setter Property="FontWeight" Value="Bold" />
  <Setter Property="Padding" Value="-2,0,-1,0" />

Revision history

  • September 12, 2007 – Created the article


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Josh Smith
Software Developer (Senior) Black Pixel
United States United States
Josh creates software, for iOS and Windows.

He works at Black Pixel as a Senior Developer.

Read his iOS Programming for .NET Developers[^] book to learn how to write iPhone and iPad apps by leveraging your existing .NET skills.

Use his Master WPF[^] app on your iPhone to sharpen your WPF skills on the go.

Check out his Advanced MVVM[^] book.

Visit his WPF blog[^] or stop by his iOS blog[^].

See his website Josh Smith Digital[^].

Comments and Discussions

QuestionRectangle annotation mode Pin
Member 1173280322-Mar-21 5:05
MemberMember 1173280322-Mar-21 5:05 
PraiseExcellent, thanks very much! Pin
Mr Yossu13-Feb-20 12:22
MemberMr Yossu13-Feb-20 12:22 
QuestionExcellence job.I'm a starter of WPF.This article is helpful.Thanks! Pin
godexist14-Jun-17 15:40
Membergodexist14-Jun-17 15:40 
QuestionHow to save this annoted image for future use? Pin
Member 1040090214-Apr-14 19:59
MemberMember 1040090214-Apr-14 19:59 
AnswerRe: How to save this annoted image for future use? Pin
Member 1219784515-Mar-16 18:48
MemberMember 1219784515-Mar-16 18:48 
GeneralMy vote of 5 Pin
Antti Keskinen26-Aug-13 19:46
MemberAntti Keskinen26-Aug-13 19:46 
QuestionClipToBounds challenge when zooming [modified] Pin
Member 193185521-Dec-08 10:37
MemberMember 193185521-Dec-08 10:37 
QuestionCreate single instance of annotation TextBox and TextBlock? Pin
Mark C Newman11-Dec-08 9:47
MemberMark C Newman11-Dec-08 9:47 
Generalproblem opening project Pin
Tim Gee13-Nov-08 12:04
MemberTim Gee13-Nov-08 12:04 
GeneralRe: problem opening project Pin
Tim Gee13-Nov-08 12:16
MemberTim Gee13-Nov-08 12:16 
GeneralRe: problem opening project Pin
Josh Smith14-Nov-08 1:31
MemberJosh Smith14-Nov-08 1:31 
GeneralRe: problem opening project Pin
Tim Gee14-Nov-08 3:18
MemberTim Gee14-Nov-08 3:18 
QuestionDrawing annotations Pin
alanp520-May-08 8:28
Memberalanp520-May-08 8:28 
AnswerRe: Drawing annotations Pin
Josh Smith20-May-08 8:32
MemberJosh Smith20-May-08 8:32 
GeneralRe: Drawing annotations Pin
alanp520-May-08 8:46
Memberalanp520-May-08 8:46 
Generalhi Pin
alireza45619-Apr-08 9:13
Memberalireza45619-Apr-08 9:13 
GeneralGreat Idea! Pin
antecedents6-Feb-08 5:33
Memberantecedents6-Feb-08 5:33 
GeneralRe: Great Idea! Pin
Josh Smith6-Feb-08 5:34
MemberJosh Smith6-Feb-08 5:34 
GeneralSave the annotated image Pin
abir1-Jan-08 23:59
Memberabir1-Jan-08 23:59 
GeneralRe: Save the annotated image Pin
Josh Smith2-Jan-08 2:58
MemberJosh Smith2-Jan-08 2:58 
GeneralRe: Save the annotated image Pin
abir10-Jan-08 23:07
Memberabir10-Jan-08 23:07 
GeneralRe: Save the annotated image Pin
Josh Smith11-Jan-08 2:23
MemberJosh Smith11-Jan-08 2:23 
GeneralRe: Save the annotated image Pin
antecedents6-Feb-08 5:31
Memberantecedents6-Feb-08 5:31 
GeneralRe: Save the annotated image Pin
Member 1219784515-Mar-16 18:55
MemberMember 1219784515-Mar-16 18:55 
GeneralRe: Save the annotated image Pin
Member 1219784516-Mar-16 22:43
MemberMember 1219784516-Mar-16 22:43 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.