---+Pivot Collections (Part 3)

---++Contents

Part 1: [[VirtSparqlCxml][Introduction]]

Part 2: [[VirtSparqlCxml][SparqlCxml]]

Part 3: <nowiki>SparqlCxml</nowiki> Deep Zoom Collections

   * [[#AncSparqlCxmlDzcs][<nowiki>SparqlCxml</nowiki> Deep Zoom Collections]]
      * [[#AncDynamicDeepZoomCollections][Dynamic DZCs]]
      * [[#AncSupportedImageFormats][Supported Image Formats]]
      * [[#AncImageCaching][Image Caching]]
   * [[#AncPivotIcons][Default Images for Pivot Collections]]
      * [[#AncSparqlCxmlIconOntology][<nowiki>SparqlCxml</nowiki> Icon Ontology]]
      *  [[#AncAddingYourOwnIcons][Adding Your Own Icons]]
   * [[#AncQrCodes][QR Codes]]

Part 4: [[VirtSparqlCxmlPivotViewer][PivotViewer]]

Part 5: [[VirtSparqlCxmlImport][Importing CXML]]

Part 6: [[VirtSparqlCxmlFacetPivotBridge][Facet Pivot Bridge]]

Part 7: [[VirtSparqlCxmlDETs][DETs : Persisting SPARQL Query Results to DAV]]

Part 8: [[VirtSparqlCxmlFAQs][Frequently Asked Questions (FAQs)]]

Part 9: [[VirtSparqlCxmlGlossary][Glossary]]

---
#AncSparqlCxmlDzcs
---++<nowiki>SparqlCxml</nowiki> Deep Zoom Collections

#AncDynamicDeepZoomCollections
---+++Dynamic DZCs

<nowiki>SparqlCxml</nowiki> generates Deep Zoom collections (DZCs) dynamically. Source images identified in the SPARQL query, either through the ?image reserved query variable or through graph virtcxml, are retrieved, stored and converted to Deep Zoom Image (DZI) format when a collection is generated.

An item's image is fetched asynchronously using an HTTP GET, multiplexed over a thread pool, and then stored in table <nowiki>DB.DBA.DZC_IMAGE_CACHE</nowiki>. Icons for items without a custom image are handled similarly - the icon is retrieved from <nowiki>WebDAV</nowiki> and again stored in <nowiki>DZC_IMAGE_CACHE</nowiki>. An image tile is created on demand at the time <nowiki>PivotViewer</nowiki> requests it. Each tile is then cached as a BLOB in table <nowiki>DB.DBA.DZC_TILE</nowiki>.

The image tiles and XML descriptor files which constitute a DZC are not stored in a web-accessible directory tree. Rather than serving files, the HTTP response content is derived directly from the database; from table <nowiki>DZC_TILE</nowiki>, in the case of image tiles, or tables <nowiki>DZC_COLLECTION</nowiki> and <nowiki>DZC_LIST</nowiki> in the case of the descriptor files. <nowiki>SparqlCxml</nowiki> creates a virtual directory "/<nowiki>DeepZoomCache</nowiki>/" for this purpose and associates it with a handler procedure WS.WS."/!<nowiki>DeepZoomCache</nowiki>/". The CXML generated by <nowiki>SparqlCxml</nowiki> includes an Items element with attribute <nowiki>ImgBase</nowiki> pointing to /<nowiki>DeepZoomCache</nowiki>/. e.g  &lt;<nowiki>Items ImgBase="http://lod.openlinksw.com/DeepZoomCache/cxml29.dzc"</nowiki>&gt;. Consequently all HTTP requests to "<nowiki>/DeepZoomCache/</nowiki>?" are intercepted by this handler.

Path formats recognized include:
   * <nowiki>/DeepZoomCache/cxml%d.dzc</nowiki>
   * <nowiki>/DeepZoomCache/%d.dzi</nowiki>
   * <nowiki>/DeepZoomCache/%d_files/%d/%d_%d.%s</nowiki>

(The path formats are described using printf format specifiers)

#AncSupportedImageFormats
---+++Supported Image Formats

The DZC generation supports both the JPEG and PNG image formats, with JPEG as the preferred option. (PNGs used as icons may occasionally display with a black background as an artifact of processing with <nowiki>ImageMagick</nowiki>.) Silverlight itself does not handle GIFs.

#AncImageCaching
---+++Image Caching

Deep Zoom images generated by <nowiki>SparqlCxml</nowiki> are cached for 24 hours, after which they will be regenerated when next requested. Requesting the image within this 24 hour window resets its 'time to live' to 1 day.

Images loaded by <nowiki>DZC_LOAD_IMAGE</nowiki>() have the date and time of their last use recorded. When caching an image, <nowiki>DZC_LOAD_IMAGE</nowiki>() first checks table <nowiki>DB.DBA.DZC_IMAGE_CACHE</nowiki> to see if the image with the given URI has already been cached. If found, it's 'last use' timestamp is updated to 24 hours from the current time, similarly when adding an image to the cache for the first time. Each time <nowiki>DZC_LOAD_IMAGE()</nowiki> is called, it deletes any cached images, and the corresponding image tiles, with a 'last use' timestamp older than the current time.

If for some reason you need to force the image cache to be cleared, you can use procedure DB.DBA.DZC_RESET (). This routine deletes the contents of all the tables used by the <nowiki>SparqlCxml</nowiki> DZC generation, i.e. <nowiki>DB.DBA.DZC_IMAGE_CACHE, DB.DBA.DZC_TILE, DB.DBA.DZC_COLLECTION and DB.DBA.DZC_LIST</nowiki>

*Warning*: Use this routine with caution. Whilst CXML-generating queries executed against a /sparql endpoint can regenerate DZCs as needed, this is *not* the case for CXML snapshots generated from the /fct endpoint and the Facet Pivot Bridge. Clearing the DZC cache will break these snapshots. Because the source query used to create them is not recorded, the associated DZC cannot be recreated transparently. Facet Pivot Bridge CXML snapshots must be created from scratch if the DZC cache is cleared.

#AncPivotIcons
---++ Default Images for Pivot Collections

While the SPARQL CXML generation is able to generate a Deep Zoom image (DZI) for a collection item from an image associated with it, it is not a requirement that every item in the collection has one. If a depiction of the item is not available, <nowiki>SparqlCxml</nowiki> substitutes an icon for the missing image. A small set of icons is included in the <nowiki>SparqlCxml</nowiki> VAD to provide a base set of default images, together with an icon ontology and icon data graph which controls which icon is used for a particular item type. The base set of icons and the icon data graph can be customised to include default images reflecting the application domain the collection data is drawn from.

The form of the SPARQL SELECT query determines whether items without a depiction (custom image) are included in the collection and hence whether icons will be used. For items without custom images to be included, the image triple pattern must be qualified by the OPTIONAL keyword.

e.g.
<verbatim>
prefix foaf: <http://xmlns.com/foaf/0.1/>
prefix ski: <http://www.openlinksw.com/ski_resorts/schema#>
prefix camp: <http://www.openlinksw.com/campsites/schema#>

select * where 
{
  { 
    ?s a ski:SkiResort . ?s ?p ?o . optional { ?s foaf:depiction ?image } 
  }
  union
  {
    ?s a camp:Campsite . ?s ?p ?o . optional { ?s foaf:depiction ?image }
  }
}
</verbatim>

The  image below shows part of the resulting Pivot collection. The piste map images are provided by the foaf:depiction predicates. Ski resorts without an associated piste map image use the 'earth' icon as a fallback image. Campsites without a custom image use the 'parasol' icon. <br/>
<img src="%ATTACHURLPATH%/pivot_icons1.jpg" style="wikiautogen"/>

Similarly for DESCRIBES, the collection created by the query
<verbatim>
prefix foaf: <http://xmlns.com/foaf/0.1/>

describe ?s where { ?s a ski:SkiResort . }
</verbatim>
will include all ski resorts, using icons for any without custom images; whereas
<verbatim>
prefix foaf: <http://xmlns.com/foaf/0.1/>

describe ?s where { ?s a ski:SkiResort ; foaf:depiction ?depiction }
</verbatim>
will include in the collection only those with custom images.

#AncSparqlCxmlIconOntology
---+++<nowiki>SparqlCxml</nowiki> Icon Ontology

Which icon is used for a collection item without its own custom image is controlled through the icon ontology defined by schema graph &lt;<nowiki>http://www.openlinksw.com/schemas/virtpivot</nowiki>&gt;, icon instance data in graph &lt;<nowiki>http://www.openlinksw.com/virtpivot/icons</nowiki>&gt; and rules in graph &lt;virtpivot-rules&gt;. (The corresponding source files in DAV/VAD/sparql_cxml are <nowiki>virtpivot_icon_ontology.n3</nowiki>, <nowiki>virtpivot_icon_instance_data.n3</nowiki> and <nowiki>virtpivot_rules.sql</nowiki> respectively.) Together, the icon schema graph and instance data define various generic display classes: vpi:Thing, vpi:Person, vpi:Place, vpi:Book, vpi:Music etc and associate an icon with each, e.g. <nowiki>vpi:ThingIcon, vpi:PersonIcon</nowiki> etc. The default icon set (generated by <code>describe ?s from &lt;virtpivot-icon-test&gt; where { ?s ?p ?o }</code>) is shown below.

<img src="%ATTACHURLPATH%/icon_collection.jpg" style="wikiautogen"/><br/>
[[http://linkeddata.uriburner.com/PivotViewer/?url=http%3A%2F%2Flinkeddata.uriburner.com%2Fsparql%2F%3Fdefault-graph-uri%3D%26should-sponge%3D%26query%3Ddescribe%2B%253Fs%2Bfrom%2B%253Cvirtpivot-icon-test%253E%2Bwhere%2B%7B%2B%253Fs%2B%253Fp%2B%253Fo%2B%7D%26debug%3Don%26timeout%3D%26format%3Dtext%252Fcxml%26CXML_redir_for_subjs%3D%26CXML_redir_for_hrefs%3D%26save%3Ddisplay%26fname%3D%23%2524facet0%2524%3DSubject%2520Type%26%2524view%2524%3D1%26%24tab%24%3D0%26%24zoom%24%3D2][View Pivot collection]]

The set of predefined <nowiki>DisplayClass</nowiki>es includes:<br/>
<nowiki>AddressBook, BeachResort, Book, BookmarkFolder, Briefcase, Business, Calendar, Community, ElectronicGood, Event, ImageGallery, MailMessage, MessageBoard, Music, Person, Place, SkiResort, SubscriptionList, SurveyCollection, Thing, TouristDestination, VCard, Weblog, Wiki</nowiki>

The actual image to use for an icon is set through the <nowiki>vp:has_dzi_source</nowiki> property. e.g.:
   * <nowiki>vpi:ThingIcon vp:has_dzi_source "linkeddata"</nowiki> .
   * <nowiki>vpi:Business vp:has_dzi_source "factory_300w"</nowiki> .

The corresponding images used to generate the icon Deep Zoom images (DZIs) can be found in <nowiki>WebDAV</nowiki> folder <nowiki>DAV/VAD/sparql_cxml/generic_dzc_images</nowiki>, e.g. <nowiki>linkeddata.jpg</nowiki>, <nowiki>factory_300w.jpg</nowiki> etc.

 Which icon is displayed as a fallback image for a particular item is determined by entries in graph &lt;virtpivot-rules&gt; which corresponds to the rule set 'virtpivot-rules' created by <nowiki>DAV/VAD/sparql_cxml/virtpivot_rules.sql</nowiki>. The rule set provides an inference context for SPARQL CXML when selecting icons. For more information on rule sets, please refer to the Virtuoso Documentation, section  [[http://docs.openlinksw.com/virtuoso/rdfsparqlrule.html][Inference Rules & Reasoning]]. The extract below, taken from <nowiki>virtpivot_rules.sql</nowiki>, shows some of the rules defined.
<verbatim>
DB.DBA.TTLP ('
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix vpi: <http://www.openlinksw.com/virtpivot/icons/> .
@prefix c: <http://www.w3.org/2002/12/cal/icaltzd#> .
@prefix cal: <http://www.w3.org/2002/12/cal#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix sioc: <http://rdfs.org/sioc/ns#> .
@prefix sioct: <http://rdfs.org/sioc/types#> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .

c:Vevent rdfs:subClassOf vpi:Event .
cal:vevent rdfs:subClassOf vpi:Event .
foaf:Person rdfs:subClassOf vpi:Person .
vcard:VCard rdfs:subClassOf vpi:VCard .

sioct:AddressBook rdfs:subClassOf vpi:AddressBook .
sioct:BookmarkFolder rdfs:subClassOf vpi:BookmarkFolder .
sioct:Briefcase rdfs:subClassOf vpi:Briefcase .
sioct:Calendar rdfs:subClassOf vpi:Calendar .
sioc:Community rdfs:subClassOf vpi:Community .
sioct:ImageGallery rdfs:subClassOf vpi:ImageGallery .
sioct:MailMessage rdfs:subClassOf vpi:MailMessage .
sioct:MessageBoard rdfs:subClassOf vpi:MessageBoard .
sioct:SubscriptionList rdfs:subClassOf vpi:SubscriptionList .
sioct:SurveyCollection rdfs:subClassOf vpi:SurveyCollection .
sioct:Weblog rdfs:subClassOf vpi:Weblog .
sioct:Wiki rdfs:subClassOf vpi:Wiki .
...
', '', 'virtpivot-rules');

rdfs_rule_set ('virtpivot-rules', 'virtpivot-rules');
</verbatim> 

To specify that a particular icon should be used to represent an instance of a class, add an entry to virtpivot-rules which declares that class as a subclass of the <nowiki>DisplayClass</nowiki> represented by the icon, then refresh the rule set by executing <nowiki>rdfs_rule_set</nowiki> ('virtpivot-rules', 'virtpivot-rules').

#AncAddingYourOwnIcons
---+++Adding Your Own Icons

The default icon collection is intended only to provide a small set of icons for a sample of broad concepts and the main entity types handled by ODS applications. You can add your own icons, to represent entity types specific to your own application domain, by copying them to the <nowiki>WebDAV</nowiki> folder <nowiki>DAV/VAD/sparql_cxml/generic_dzc_images</nowiki> and adding entries to graph &lt;<nowiki>http://www.openlinksw.com/virtpivot/icons</nowiki>&gt; to define new <nowiki>DisplayClass</nowiki> and <nowiki>DisplayClassIcon</nowiki> instances.

Suppose, for example, that you had defined your own vehicle ontology, hosted at <nowiki>http://purl.org/vehicle_ontol/v1#</nowiki>, and wanted to add an automobile icon to the icon set to represent instances of vehicle classes from this ontology. Assuming your icon is to be provided by image file "sports_car.jpg", the additions needed to incorporate it might look as follows:

---+++++Graph <nowiki>http://www.openlinksw.com/virtpivot/icons</nowiki>:
<verbatim>
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix vp: <http://www.openlinksw.com/schemas/virtpivot#> .
@prefix vpi: <http://www.openlinksw.com/virtpivot/icons/> .

vpi:Automobile
	a vp:DisplayClass ;
	rdfs:label "Automobile (DisplayClass)" ;
	rdfs:comment "The DisplayClass type used to represent an automobile" ;
	vp:has_icon vpi:AutomobileIcon ;
	vp:display_class_category "vehicles" .

vpi:AutomobileIcon
	a vp:DisplayClassIcon ;
        rdfs:label "Automobile icon" ;
	rdfs:comment "Pivot icon for an entity belonging to the 'Automobile' DisplayClass" ;
	vp:has_dzi_source "sports_car" ;
	vp:belongs_to_icon_collection vpi:GenericIcons1 .
</verbatim>

---+++++Graph virtpivot_rules:
<verbatim>
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix veh: <http://purl.org/vehicle_ontol/v1#> .
@prefix vpi: <http://www.openlinksw.com/virtpivot/icons/> .

veh:Hatchback rdfs:subClassOf vpi:Automobile . 
veh:Saloon rdfs:subClassOf vpi:Automobile .
veh:SportsCar rdfs:subClassOf vpi:Automobile . 
</verbatim>
With these changes, any veh:Hatchback, veh:Saloon or <nowiki>veh:SportsCar</nowiki> instance in the collection will, in the absence of a custom image, be represented by the <nowiki>sports_car</nowiki> icon.

#AncQrCodes
---++QR Codes

Virtuoso's CXML support includes the ability to generate [[http://en.wikipedia.org/wiki/QR_Code][QR codes]] for collection items. Each item's QR code typically encodes a string identifier. This is normally the item's URI, which courtesy of Linked Data, can serve as a globally unique dereferenceable ID providing a link to further information about the item. However, the content used for the QR code is configurable and any item facet can be used, for instance a product SKU (stock keeping unit) or UPC (universal product code). A generated QR code can appear in PivotViewer adjacent to the item's custom or default image, or be used alone as the main depiction. The choice of which is used is controlled through the [[VirtSparqlCxml][SPARQL reserved query variables]] ?image and ?qrcode.