Manual:

First PagePrevious PageBack to overview


WildPassport

WildPassport is the name of a generic patterning data system implemented by Wildbook. Using this system, any type of pattern-matching data can be saved and retrieved from photos (or other media files) attached to an encounter. The fundamental structure used in WildPassport is the PatterningPassport, which is simply an XML file consisting mostly of patterning data.

Wildbook instance will store the XML pattern data in a database and as XML files alongside the associated media files. The actual schema of the patterning data XML is of no concern to Wildbook instance, as long as it doesn't use patterningPassport as its root node name. The pattern processing and storage is only connected to Wildbook server by communication through the WildPassport servlets.

PatterningPassport format

For every photo or media file attached to an Encounter, there is a Patterning Passport (PP). The PP is a set of XML data in two parts: the ID Data and the Pattern Data. The structure of the XML file is as follows:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<patterningPassport>

<idData>
<encounterId>12345678</encounterId>
<mediaId>1</mediaId>
<encounterUrl>http://shepherd.foo.org/ProjectXYZ/encounters/encounter.jsp?number=12345678</encounterUrl>
<mediaSourceUrl>http://shepherd.foo.org/shepherd_data_dir/encounters/12345678/fooBar.png</mediaSourceUrl>
<passportXmlUrl>http://shepherd.foo.org/shepherd_data_dir/encounters/12345678/1_pp.xml</passportXmlUrl>
</idData>

<customXmlNode note="This node contains all pattern matching data for the referenced media.">
<testnode1>Foo</testnode1>
<testnode2>Bar</testnode2>
</customXmlNode>

</patterningPassport>

Note that, when creating or updating a PatterningPassport on Wildbook instance, the only required XML is the pattern matching data itself (marked as “customXmlNode” here). The document wrapper (“patterningPassport”) and meta-data (“idData”) are created automatically by the WildPassport system.

Setting the PatterningPassport

To set a new PP or update an existing PP, use the EncounterSetPatterningPassport servlet. Setting a PP requires three parameters:

  1. An Encounter ID (encounterId String)
  2. A Media ID (mediaId String)
  3. Well-formed XML file representing the patterning in the media file (patterningPassportData File)

The format of the call to the servelet is:

http://shepherd.foo.org/EncounterSetPatterningPassport?encounterId=123456&mediaId=45&patterningPassportData=[[File]]

The recognized parameters in the request are: encounterId (String), mediaId (String), and patterningPassportData (File).

Note: Only one file should be attached, and it must be a well-formed XML file.

A web interface is provided for testing and convenience, see uploadPatterningPassport.jsp.

Requirements

Failure to satisfy these requirements will result in a set failure. * A valid combination of encounterId and mediaId must be provided. * The XML file provided must be well-formed.

Response

Response from the EncounterSetPatterningPassport servlet is in XML, taking one of the following forms:

<response><success>Success Message</success></response>

or

<response><error>Failure Message</error></response>

Updating the PatterningPassport

There are two ways to update an existing PP:

  1. RENEW: Follow the instructions to create a new PP, including an updated patterningPassportData XML file
  2. VERBATIM OVERWRITE: Send a fully formed PP XML file (i.e. with wrapper and metadata)

The second method is available just as a convenience and it's usually better to use the first method. A use case for this would be to download a set of XML files, tweak them slightly with a script, then send them back up wholesale.

The first method will regenerate the site-based metadata (e.g. the idData node) based on the latest server settings. And the second method will simply save what XML it is given, provided it is well-formed.

To invoke the direct PP XML overwrite, simply include the full PP XML file as the patterningPassportData (File) parameter when accessing the servlet. Strictly speaking, anything with a base node with the node name patterningPassport will be treated as a verbatim passport.

Retrieving a single PatterningPassport

Use the EncounterGetPatterningPassport servlet to retrieve a single PP. This servlet accepts three parameters:

  • encounterId (String)– The ID of the Encounter
  • mediaId (String) – The index/ID of the media file associated with the encounter
  • jdoql (String) – Optional JDOQL string to narrow the results

If there is a matching PP, the XML file will be returned. Otherwise, an XML-formatted response will return an empty set.

Retrieving a set of PatterningPassports

As with retrieving a single PP, use the EncounterGetPatterningPassport servlet.

To retrieve all PPs – leave all three parameters blank.

To retrieve all PPs for a single encounter – leave all but the encounterId blank.

To retrieve all PPs matching a query – use a JDOQL string as the jdoql parameter.

Responses will be in the form of an XML list in the following format:

<response>
<patterningPassport encounterId="12345" mediaId="1" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/12345/1_pp.xml"/>
<patterningPassport encounterId="12345" mediaId="2" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/12345/2_pp.xml"/>
<patterningPassport encounterId="12345" mediaId="3" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/12345/3_pp.xml"/>
<patterningPassport encounterId="678910" mediaId="1" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/678910/1_pp.xml"/>
<patterningPassport encounterId="678910" mediaId="2" patterningPassportXmlUrl="http://shepherd.foo.org/shepherd_data_dir/encounters/678910/2_pp.xml"/>
</response>

Note that there is a node named response containing child nodes for each of the matching PP objects on the server. Included as properties on each of those patterningPassport child nodes are the encounterId, the mediaId, and the patterningPassportXmlUrl. The latter is used to retrieve the full XML of the PP.

There is a helper/test web interface for retrieving sets of PP data, see getPatterningPassport.jsp.

Development: How PatterningPassports are stored

The PatterningPassport object is persisted in the database as a property of every SinglePhotoVideo object. The XML data for the PatterningPassport is stored in the object and as a separate XML file in the data directory of Wildbook instance.

The org.ecocean.PatterningPassport class governs the structure of the XML, and of course the variables of the object. The most important method of this class is makeNewPassportXml, which puts together the XML file that will both be stored in the database and written to the file system.

The filename for the XML is determined by the ID (not the filename) of the media with which it is associated. By default, this file is stored in the same directory as the image/media itself. For example, if the ID of the photo is “99”, the photo may be stored as “99.png” and the PP XML would be “99_pp.xml”.

In standard configuration of Wildbook, these files would be in a directory called …\shepherd_data_dir\encounters\12345678 (if “12345678” is the encounter ID).