Merge pull request #321 from IIIF/0305-enhance-svg-discussion-in-262

Enhance svg discussion in #261

recipe/0261-non-rectangular-commenting/index.md

@@ -1,5 +1,5 @@
 ---
-title: Annotation with a Non-Rectangular Polygon
+title: Annotation with a Non-Rectangular Polygon (Updated)
 id: 261
 layout: recipe
 tags: [images, commenting, annotation]
@@ -12,29 +12,50 @@ topic: annotation
 
 ## Use Case
 
-For a IIIF resource, you would like to add a simple annotation to the resource, where the area of the resource you would like to highlight is not a rectangle. The shape of the focus area needs to be delineated with precision to highlight only the portion of the image that is relevant to the annotation.
+For a IIIF resource, you would like to add a simple annotation whose target area is not a rectangle. The shape of the focus area needs to be delineated with precision to highlight only the portion of the image that is relevant to the annotation.
 
 ## Implementation Notes
 
 The [IIIF Presentation 3.0 API][prezi3] does not itself discuss non-rectangular annotations, incorporating them from the [W3C Web Annotation Data Model](http://w3.org/TR/annotation-model/) by reference. For a full description of this and other web annotations used in IIIF annotations, we recommend you read that document.
 
-The W3C data model requires non-rectangular polygonal annotations to be described in the Scalable Vector Graphic (SVG) markup format. Note that client parsing of SVG varies, and valid SVG may not display as you expect.
+The W3C data model requires non-rectangular annotations to be described in the Scalable Vector Graphic (SVG) markup format and to use the `SvgSelector`. Note that viewer parsing of SVG varies, and valid SVG may not display as you expect. SVGs have the potential to be highly complex; this example is highly simplified for the purpose of demonstrating an entry point into IIIF affordances.
 
 When reviewing your SVG data, remove all styling and transformation features, per [the W3C data model](https://www.w3.org/TR/annotation-model/#svg-selector). To ensure your SVG markup is valid, you can use the [W3C validator](https://validator.w3.org/). SVG can be valid markup as absolute points in a coordinate space or as relative points along a path. 
 
 Sizing and placement of the SVG polygon in relation to its `target` takes some special attention. If the `target` is the entire Canvas, then the SVG viewport is assumed to cover the entire Canvas. On the other hand, if the SVG's coordinates are mapped to a part of a Canvas, then its `target` must be the rectangular bounding box of the Canvas in which the SVG viewport should be placed. If the dimensions of the viewport and its target region (either the bounding box or the entire Canvas) are not the same, then the SVG must be scaled such that it covers the region. This may result in different scaling ratios for the X and Y dimensions.
 
+### Additional Notes on SVG
+
+SVG implementations and affordances occupy a large and complex space. Not all implementations have the same affordances, and not all affordances are present in all implementations. To take just one facet of SVG creation software, the output from one such tool may set an origin point at the upper left corner of a bounding box while another may set an origin in the lower left corner. Conventional browser support is equally complex: All major browsers natively [provide basic support](https://caniuse.com/svg), though tiles don't scale properly in MS Edge and important details such as `img` vs `object` container support are not considered "basic", at least by this common matrix.
+
+#### For Viewers
+Browser-based IIIF viewers often hand off SVG rendering to the containing browser, but it might be helpful to non-browser–based viewers to detail recommended SVG feature support. In view of the complexity described above, and acknowledging that expecting viewers to implement the full SVG specification on a Canvas is impractical as well as contrary to the W3C Web Annotation specification, this recipe suggests that viewers handling SVG rendering themselves support at least the following features:
++ named shapes
+	+ `circle`
+	+ `ellipse`
+	+ `line`
+	+ `polyline`
+	+ `polygon`
++ `viewBox`
++ `g` 
++ `path`, including multiple `path`s inside a `g`
+
+Viewers may occasionally encounter manifests in which there is a conflict between the dimensions values for a resource or IIIF property and the dimensions given within the SVG markup of an `SvgSelector` property. To anticipate these cases, it is suggested that viewers privilege the dimensional information contained in IIIF properties other than `SvgSelector` over the SVG dimensions where these conflict. 
+
+#### For Manifest Creators
+Manifest creators should ensure, for maximum compatibility with viewers, that any non-rectangular annotations are limited to the above list as well. Going beyond this list, or keeping to the SVG features contained therein but adding interaction or multiplicity of them, risks your non-rectangular annotations not appearing in a viewer. In the case of SVG non-rectangular annotations, it may not be feasible for viewers to display only the supported features and discard the rest, as they can do for manifests more generally. A pattern that has shown some promise is to place the essential selector `path` inside an initial `g` element of the SVG, with an additional following `g` element holding presentation-only data.
+
 ## Restrictions
 
 This approach should not be used to describe non-rotated rectangular regions.
 
 ## Example
 
-In this Manifest, we are highlighting a fountain with a statue on top of it in Göttingen, and imagining that we want to be fairly precise in our highlight. The client should not show the bounding box on the image.
+In this Manifest, we are highlighting a fountain with a statue on top of it and imagining that we want to be fairly precise in our highlight. The client should not show the bounding box on the image.
 
 {% include manifest_links.html viewers="Mirador,Annona" manifest="manifest.json" %}
 
-{% include jsonviewer.html src="manifest.json" %}
+{% include jsonviewer.html src="manifest.json" config='data-line="44-70"' %}
 
 ## Related Recipes
 

recipe/0261-non-rectangular-commenting/manifest.json

@@ -60,8 +60,8 @@
                 "type": "SpecificResource",
                 "source": "{{ id.path }}/canvas/p1",
                 "selector": {
-                    "type": "SvgSelector",
-                    "value": "<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'><g><path d='M270.000000,1900.000000 L1530.000000,1900.000000 L1530.000000,1610.000000 L1315.000000,1300.000000 L1200.000000,986.000000 L904.000000,661.000000 L600.000000,986.000000 L500.000000,1300.000000 L270,1630 L270.000000,1900.000000' /></g></svg>"
+                  "type": "SvgSelector",
+                  "value": "<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'><g><path d='M270.000000,1900.000000 L1530.000000,1900.000000 L1530.000000,1610.000000 L1315.000000,1300.000000 L1200.000000,986.000000 L904.000000,661.000000 L600.000000,986.000000 L500.000000,1300.000000 L270,1630 L270.000000,1900.000000' /></g></svg>"
                 }
               }
             }
@@ -70,4 +70,4 @@
       ]
     }
   ]
-}
+}