Annotation Management

Starting from DDV 2.0, Annotation functionality is supported. This guide introduces some of the key Annotation features. The following functionalities can all be achieved through bulit-in Elements which are related to annotation functionality, this guide only focuses on programming methods.

It is important to note that annotations on the page can be displayed in the UI of either the EditViewer or the BrowseViewer, but they can only be processed through the UI in the EditViewer. Additionally, built-in Elements related to annotation functionality can only be configured within the UiConfig of the EditViewer.

Annotation creation

Supported annotation types

Up to now, the annotation types supported by DDV are as follows:

Create a specified type annotation instance

To add an annotation to the page, first of all, you need to create an annotation instance. Take the rectangle annotation as an example,

// Given that editViewer is an existing instance of EditViewer and a document is currently open.
const pageUid = editViewer.indexToUid(0);
const rect = Dynamsoft.DDV.annotationManager.createAnnotation(pageUid, "rectangle"); // Create a default Rectangle annotation instance.

The following properties of the annotation can be accessed from the created instance.

Annotation Uid

Each annotation possesses a unique annotation uid.
```
  const annotUid = rect.uid;
```
Page uid where the annotation is located
```
  const annotPageUid = rect.pageUid;
```
If the annotation is be deleted, the pageUid will return ''.
Creation date & Modification date
```
  const creationDate = rect.creationDate; //D:YYYYMMDDHHmmSSOHH'mm'
  const modificationDate = rect.modificationDate; //D:YYYYMMDDHHmmSSOHH'mm'
```
If the annotation is be deleted, the modificationDate will return ''.

If the annotation is created but not be modified after adding, modificationDate equals to creationDate.

Modify the annotation options while creating

If no specific options are passed during the creation of the annotation instance, the generated annotation will have default options.

If you wish to create a custom-configured annotation, you can pass in the specified configuration during creation.

For example, to create a rectangle annotation whose border color is red and background is green.

const rectOptions = {
    borderColor: "red",
    background: "green",
};

// Given that editViewer is an existing instance of EditViewer and a document is currently open.
const pageUid = editViewer.indexToUid(0);

const rect = Dynamsoft.DDV.annotationManager.createAnnotation(pageUid, "rectangle", rectOptions);

Modify the annotation options dynamically after creating

After creating the annotation, if you want to dynamically modify its configuration, you can use updateOptions() method.

For example, to modify an existing rectangle annotation.

const newRectOptions = {
    borderWidth: 2.66,
};

rect.updateOptions(newRectOptions);

Even after the annotation has been created to the page by createAnnotation(), updating the options will lead to instant changes in the displayed annotation on the page.

Create an annotation instance after image cropping

After cropping, if no specific options are passed during the creation of the annotation instance, the generated annotation will use default options, which might result in it being invisible.

If you want the annotation to be visible, you can pass specific configurations during its creation.

For example, after cropping an image, if you wish to create a rectangle annotation at position (10, 10) within the visible area.

const pageData = await editViewer.currentDocument.getPageData(editViewer.getCurrentPageUid());

const rectOptions = {
    x: pageData.cropBox.left + 10,
    y: pageData.cropBox.top + 10,
};

// Given that editViewer is an existing instance of EditViewer and a document is currently open.
const pageUid = editViewer.indexToUid(0);

const rect = Dynamsoft.DDV.annotationManager.createAnnotation(pageUid, "rectangle", rectOptions);

More features

Add image to the page by using Stamp Annotation

Observing the structure of StampAnnotationOptions, the data type of stamp is EnumStampIcon or Blob. When stamp is set to EnumStampIcon, it indicates that the generated annotation will be displayed as a standard business stamp icon, with the default value being draft. When stamp is set to EnumStampIcon, it indicates that the generated annotation will be displayed as a standard business stamp icon, with the default value being draft. When stamp is set to a Blob, such as the blob of a custom image, it means the annotation will be displayed as an image.

The supported types of standard business stamps are as follows:

EnumStampIcon	Corresponding stamp
REJECTED
ACCEPTED
INITAL_HERE
SIGN_HERE
WITNESS
APPROVED
NOT_APPROVED
DRAFT
FINAL
COMPLETED
CONFIDENTIAL
VOID

If set to blob, the custom image will be added as the stamp.

var blob = /*Sample image blob*/;

const stampOptions = {
    stamp: blob,
};

// Given that editViewer is an existing instance of EditViewer and a document is currently open.
const pageUid = editViewer.indexToUid(0);

const stamp = await Dynamsoft.DDV.annotationManager.createAnnotation(pageUid, "stamp", stampOptions);

Configure the styling for the part content of text within TextBox annotation or TextTypewriter annotation

The textContents attribute in the TextBoxAnnotationOptions and TextTypewriterAnnotationOptions accepts an array of TextContent, which means that even within the same text annotation, you can configure specified text content with different styles.

For example,

const testTextContents = [
    {
        content: "Dynamsoft Document Viewer ",
        color: "red",
    },
    {
        content: "Annotation feature",
        color: "green",
        underline: true,
    }
];

const textBoxAnnotationOptions = {
    textContents: testTextContents,
};

// Given that editViewer is an existing instance of EditViewer and a document is currently open.
const pageUid = editViewer.indexToUid(0);

const textBox = Dynamsoft.DDV.annotationManager.createAnnotation(pageUid, "textBox", textBoxAnnotationOptions);

Delete annotation(s)

Delete all annotations which are located on the specified page using getAnnotationsByPage() and deleteAnnotations().

// Given that editViewer is an existing instance of EditViewer and a document is currently open.
const curPageUid = editViewer.getCurrentPageUid();; // Get the page uid of current page in the edit viewer

const annotations = Dynamsoft.DDV.annotationManager.getAnnotationsByPage(curPageUid);

const annotationUids = annotations.map(obj=>obj.uid);

Dynamsoft.DDV.annotationManager.deleteAnnotations(annotationUids);

Delete all annotations which are located in the specified doc using getAnnotationsByDoc() and deleteAnnotations().

// Given that editViewer is an existing instance of EditViewer and a document is currently open.
const curDocUid = editViewer.currentDocument.uid; // Get the doc uid of current document which is open in the edit viewer

const annotations = Dynamsoft.DDV.annotationManager.getAnnotationsByDoc(curDocUid);

const annotationUids = annotations.map(obj=>obj.uid);

Dynamsoft.DDV.annotationManager.deleteAnnotations(annotationUids);

Delete selected annotations using getSelectedAnnotations and deleteAnnotations().

// Given that editViewer is an existing instance of EditViewer and a document is currently open.
const annotations = editViewer.getSelectedAnnotations(); // Get the selected annotations

const annotationUids = annotations.map(obj=>obj.uid);

Dynamsoft.DDV.annotationManager.deleteAnnotations(annotationUids);

Change layer of an annotation

In the same page, annotations maintain a hierarchical relationship with each other. If you intend to alter the hierarchical level of an annotation, you can employ the following methods.

Bring forward using bringAnnotationForward()

  Dynamsoft.DDV.annotationManager.bringAnnotationForward(rect.uid);

Send backward using sendAnnotationBackward()

  Dynamsoft.DDV.annotationManager.sendAnnotationBackward(rect.uid);

Bring to front using bringAnnotationToFront()

  Dynamsoft.DDV.annotationManager.bringAnnotationToFront(rect.uid);

Send to back using sendAnnotationToBack()

  Dynamsoft.DDV.annotationManager.sendAnnotationToBack(rect.uid);