Mindswap Jena Multimedia API v 1.0


Author: Michael Grove
For: MINDSWAP

Introduction

PhotoStuff is an image annotation tool. It allows a user to create markup about images available on the web. Some assertions made by the tool require the use of a digital media ontology that defines concepts such as image, region, and depiction. Rather than having changes in the ontology require code changes, if specific concepts/terms are agreed upon, a generic multimedia term framework could be built. This is the motivation behind the Jena Multimedia API. A collection of generic terms found in any multimedia ontology, such as image, region and depiction, are defined in a programmatic API which is not specifically tied to an ontology. This way ontology changes will not break existing code as the code using this API does not depend on any specific ontology. The end result is that the API allows programmers to write cleaner, more readable code without having to deal with the specifics of the underlying ontology.

The API is built directly on top of Jena. Each of the concepts in the API such as Image, Region and Video extend the Jena Resource class. This allows us to leverage the polymorphism support natively provided by Jena and was part of the motivation behind building the API on top of Jena. It is also a good, simple example of how to create your own extension to the Jena Resource interface.

Examples

Defining a Model Profile

A ModelProfile represents the basic structure of a physical multimedia ontology. It provides a basic layout that maps to the core concepts in the ontology such as image, region and depiction. ModelProfile's are used by the MultimediaModel to identify exactly which resources map to the concepts in the real ontology. It provides basic access methods to get each of these concepts like image, region and depiction. Implementation's of a ModelProfile essentially capture the structure of the physical ontology they represent.

The ModelProfile associated with a MultimediaModel is the reason that the multimedia resources in the model like Image and Video must be associated with a MultimediaModel to work properly. They otherwise would have no handle to the ModelProfile and would not know which properties or classes to use when making assertions. For a full example, see MindswapMultimediaModelProfile

public class GenericModelProfile implements ModelProfile
{
    // note that this is not a complete example, it only shows a few terms to get the basic idea
    // for a more complete example, reference the documentation.

    // create the URL of our physical ontology
    private static final String ONT_URL = "http://www.example.org/multimedia/digital-media.owl#";
    // create a temporary model for us to create the actual terms with
    private static final Model ONT_MODEL = ModelFactory.createDefaultModel();

    // here we will define our classes in the ontology
    // this first term will map with the Image concept 
    // and the second will match with the Region concept
    private static final Resource Image = ONT_MODEL.createResource(ONT_URL+"Image");
    private static final Resource Region = ONT_MODEL.createResource(ONT_URL+"ImagePart");

    // here we will define some of the properties required by the ModelProfile
    // that are in our ontology
    private static final Property svgOutline = ONT_MODEL.createProperty(ONT_URL+"svgOutline");
        private static final Property depicts = ONT_MODEL.createProperty(ONT_URL+"depicts");
    private static final Property depiction = ONT_MODEL.createProperty(ONT_URL+"depiction");
    private static final Property regionOf = ONT_MODEL.createProperty(ONT_URL+"regionOf");
    private static final Property hasRegion = ONT_MODEL.createProperty(ONT_URL+"hasRegion");

    // now that we've defined all the terms that correspond to the actual physical
    // ontology, we need to start implementing the ModelProfile abstract methods
    // the implementation of these methods will tell the API which concepts to use when
    // the RDF is being generated.
    public Property depicts() {
        return depicts;
    }
    
    public Property depiction() {
        return depiction;
    }

    public Property hasRegion() {
        return hasRegion;
    }

    public Property regionOf() {
        return regionOf;
    }

    public Property svgOutline() {
        return svgOutline;
    }

    public Resource Image() {
        return Image;
    }

    public Resource Region() {
        return Region;
    }
}


Creating Images, Regions and Multimedia Models

Generally, it is the responsibility of the MultimediaModel to create new resources such as Image, Region and Video. When these resources are created, the rdf:type assertion is made in the model associated with the resource. These resources can also be created using the MultimediaFactory.

public static void main(String[] args) throws Exception
{
    org.mindswap.multimedia.impl.Mapper.mapImplementations();
        
    MultimediaModel aModel = MultimediaFactory.createMultimediaModel();
    Resource aInst = aModel.createResource("http://www.example.org/#Foo");
    Resource anotherInst = aModel.createResource("http://www.example.org/#Bar");
        
    Image aImage = aModel.createImage("http://www.example.org/images/myImage.png");
        
    Region aRegion = aModel.createRegion();
    aRegion.addDepicts(aInst);
    aImage.addRegion(aRegion);

    Video aVideo = aModel.createVideo("http://www.mindswap.org/#aVideo");
    VideoFrame aFrame = aModel.createVideoFrame();
    VideoSegment aSegment = aModel.createVideoSegment();

    aFrame.addDepicts(anotherInst);
    aFrame.setFrameNumber(10);
    aVideo.addFrame(aFrame);

    aSegment.setStartFrame(11);
    aSegment.setEndFrame(21);

    aVideo.addSegment(aSegment);
}


Using the API and registering the implementations

One of the key features of the API is that it takes advantage of Jena's polymorphism feature. If you have a handle to a Resource you know is an Image you can call .as(Image.class) to return that Resource represented as an Image. If you are not sure if the conversion to Image is valid, you can call .canAs(Image.class) to find out if your Resource object can be represented as an Image object. These two functions require implementing classes to register an Implementation factory object that will provide the functionality to test and see if the conversion is valid, and to do the actual conversion. There is a class Mapper that registers all the known implementations. When you create your own implementation, you should add a line of code to register your new object. Also, Mapper.mapImplementations should be called during initialization of any applications that use the API. If it is not called, then you will get ConversionException's when trying to convert and use the multimedia classes. Check out some source code:

See the Mapper source
Here's an example of the Implementation class for Image


Extending the API

1) Create an interface for your new media type, such as Image
    a) make sure to extend DigitalMedia, or one of the existing types like Image or Video.
2) Create an implementation for your interface, like ImageImpl
    a) be sure to extend ResourceImpl so that your newly created object is also a Jena Resource.
3) Create an Implemtation factory for your new type, like ImageImplementation
4) Add it to the Mapper
5) Add some methods to MultimediaFactory so it can be instantiated by the user
    a) perhaps add methods to MultimediaModel for convience.


Links and Resources



MINDSWAP is a W3C member