Tutorial: Burn Annotations

Web Document Viewer support "burning" annotations to the destination document. Burn means that all document annotations will be rendered on the output document page images for image files or embedded into document for PDF, when document is saved.

Annotations burning is used to add or highlight some content on a document page, or hide critical information on an image.

To burn annotation when document is saved the annotation should be explicitly marked for burn. This could be done in two ways:

• Configure or set default values for different types of annotations.
  For example,

   _viewer = new Atalasoft.Controls.WebDocumentViewer({
     // omit other configuration for simplicity
      annotations: {
         defaults: [
         {
             type: 'text',
             burn: true,
             text: {
                 font: {
                     size: 25
                 }
             }
           }]
        }
  });
  

  In this case, each created text annotation will have specified properties configured, including 'burn' property.

• Explicitly set 'burn' property annotation object.
  This could be done in a numerous ways, depending on application needs.

  • For example, it's possible to handle annotationcreated and set burn flag for each new created annotation.

    _viewer.bind('annotationcreated', function(event) {
        event.annotation.burn = true;
        event.annotation.update();
    });
    

  • Or extend annotation context menu to let user decide whether to burn annotation.

    _viewer.bind("contextmenu", function (event, annotation, menu) {
        var menuItemTitle = !annotation.burn ? "Burn" : "Not Burn";
        menu[menuItemTitle] = function (annotation) {
            annotation.burn = !annotation.burn;
            annotation.update();
        };
    });
    

Note, that burned annotations are considered as part of document image and are not saved(to XMP) separately from the document along with regular annotations.

Burn Implementation

There are two kinds of annotations burn depending on document format

• Burn annotations to the Image
  This is the straightforward case. Annotations are just became part of the image. Underlying content image are modified(highlight annotation) or replaced(black rectangle annotation), depending on the type of annotations burned.

• Burn annotations to the PDF document.
  In this case individual annotations are burned to the set of images, and then those images are added to the PDF document as a layer of image objects.

  Note, that original PDF content is not modified. I.e. if redact annotation is burned to pdf, although masked data won't be visible in the PDF viewers, it will still be in document and available through API or even text editor for those who have access to PDF file itself.

Annotation are burned in the document using standard dotImage mechanism - all annotations are rendered to AtalaImage using renderer registered in Atalasoft.Annotate.Renderer.AnnotationRenderers. So if annotation appearance should be modified or custom annotation types support added, most likely it should be done through AnnotationRenderers.

Images are normalized to PixelFormat.Pixel24bppBgr color format when there are any annotations to burn on the page.

Translate annotations to other formats

Web Document Viewer does not provide a way to save annotations to the format-specific annotations like PDF or WANG. If needed that task could be quite easily done using corresponding converter classes that dotImage SDK provides.

PDF annotations

Atalasoft.Annotate.Exporters.Pdf.AnnotationDataExporter exporter allows to convert dotImage annotations to the PDF annotations.

Note that not all dotImage annotations could be directly mapped to PDF. AnnotationDataExporter provides polyfill for such annotations, but still final result will differ from other dotImage viewers with native annotations support.

AnnotationDataExporter do support:

• shapes and text data for all types of Web Document Viewer annotations.
• fill and stroke colors according to pdf color scheme.
• position on the page even if the page was rotated or if pages were reordered.
• annotation outline thickness.

AnnotationDataExporter limitations are:

• annotation rotation in viewer causes annotation resize when converted to pdf. The new size corresponds the bounding shape for the initial rotated one.
• Fill and stroke opacity are not preserved.
• Text format (i.e. font family, font size, text color etc.) for text annotations is lost.
• Movable, selectable, resizable properties are not preserved.

There may be other limitations that are not mentioned here.

WANG annotations

dotImage SDK supports conversion of native XMP annotations to WANG(aka TIFF) annotations.

Atalasoft.Annotate.Formatters.WangFormatter.WangFormatter.Serialize API could be used to convert LayerCollection or LayerData collections of annotations to stream.