03 Defining your data model - rsimon/immarkus GitHub Wiki

Before you start working with IMMARKUS, you should define a data model. The data model has three parts:

  • The Image Metadata schema, which defines how you describe the image files in your collection.
  • The Folder Metadata schema, which defines how you record information about the directory folders in your collection. This can be useful in case your folders represent sub-collections.
  • Most importantly: the Entity Class model, which defines the classes you will use to identify Entities in your image annotations.

Entity Classes

Click the Create Entity Class button to create a new class. This will open the Entity Class editor.

  • Choose a unique identifier for the class (mandatory)
  • Pick a color (this will be for color-coding image annotations later)

Optionally:

  • Choose a user-friendly display name for your class
  • Pick a parent entity class, in case your data model is hierarchical (more below)
  • Add a description that explains how to use this entity class

On the right side of the editor, you will see a preview of how your Entity Class will appear, when used in the annotation interface.

Properties

The purpose of Entity Classes is not just to identify certain things or concepts in your annotations. They also allow you to record specific details about these things or concepts in an efficient way. In order to do this, you can define Properties for your entity class.

  • Unfold the Properties section by clicking on it.
  • Click Add Property. This will open the Property Editor.

Think of properties as metadata fields for the entities you will annotate. For example, if you annotate archaological objects, you may want to record their material.

  • Enter a name for the property, such as "Material"
  • Choose a data type for the property. For example, you may want to pre-define a number of options that you can later choose from in the annotation interface. In this case, select Options as the data type, and the values you want to be available as choices. (Don't worry - you can always edit or add values later.)

Optionally, add a description for the property. (E.g. to clarify what this property is for to other users, in case you plan to share your data model.)

Property Data Types

The following data types are currently available:

  • Text - a basic text field with no particular constraints
  • Number - a numeric field
  • Options - a list of values to choose from
  • URI - a text field which validates whether the content is a URI, and which appear clickable in the interface
  • Geo-Coordinate - a latitude/longitude coordinate pair
  • External Authority - see our guide for integrating external authority sources into your data model

Data Model Hierarchy

If you data model is hierarchical, Entity Classes will inherit the properties of their parent classes. This means you can define common properties, which should be shared among classes, at a root level. Child classes then only need to define properties that are specific to them. This way, you can save time, avoid repetition and stay consistent when defining your data model.

Example:

  • Let's assume you define a class called Geographical Feature.
  • You define two common properties Name (text) and Location (Geo-Coordinate).
  • Next, you define another class called Terrain.
  • You make Terrain a child concept of Geographical Feature.
  • You add a new property to Terrain called Terrain Type Option).

As you can see in the preview, Terrain now has three properties: Name, Location, and Terrain Type. The icons next to the Name and Location fields indicate that these are fields inherited from an ancestor class.

Image Metadata

To record metadata for your images, you first need to define a schema. Go to the Image Metadata tab, and click the New Image Schema button. This opens the Schema Editor. Choose a name for your schema, give it a description (optional), and define metadata fields.You can use the same data types as for Entity Classes (text, number, measurement, etc).

Once you have defined a schema, you can fill metadata for your images from the image gallery, as well as from the annotation view.

  • In the image gallery, click the context menu icon on the image thumbnail and select Image metadata.
  • In the annotation view, select the Metadata panel in the right sidebar.

Folder Metadata

You can record metadata for your the sub-folders in your project folder the same way. First, define a schema under the Folder Metadata tab. Click the Add Metadata Property button and use the Property Editor to define metadata fields for your folder schema.

You can fill metadata for a folder in the image gallery, by clicking the context menu icon on the folder symbol and selecting Folder metadata from the dropdown menu.