Differences

This shows you the differences between two versions of the page.

Link to this comparison view

wildpassport [2013/09/13 16:45] (current)
Line 1: Line 1:
 +//Manual:// [<>]
 +\\
  
 +====== 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.
 +
 +{{:​wildpass_high_view.png|}}
 +
 +===== 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:
 +<​code>​
 +<?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>​
 +</​code>​
 +
 +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:
 +
 +  - An Encounter ID (''​encounterId''​ String)
 +  - A Media ID (''​mediaId''​ String)
 +  - Well-formed XML file representing the patterning in the media file (''​patterningPassportData''​ File)
 +
 +The format of the call to the servelet is:
 +<​code>​http://​shepherd.foo.org/​EncounterSetPatterningPassport?​encounterId=123456&​mediaId=45&​patterningPassportData=[[File]]</​code>​
 +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:
 +<​code>​
 +<​response><​success>​Success Message</​success></​response>​
 +</​code>​
 +or
 +<​code>​
 +<​response><​error>​Failure Message</​error></​response>​
 +</​code>​
 +
 +{{:​wildpass_uml_set_patterningpassport.png|}}
 +
 +===== Updating the PatterningPassport =====
 +There are two ways to update an existing PP:
 +  - RENEW: Follow the instructions to create a new PP, including an updated **patterningPassportData** XML file
 +  - 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 [[http://​db.apache.org/​jdo/​jdoql.html|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:
 +<​code>​
 +<​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>​
 +</​code>​
 +
 +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**.
 +{{:​wildpass_uml_interaction.png|}}
 +
 +===== 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).