Skip to content
Permalink
master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

hyperimage_scripts/hyperimage_documentation.md

Go to file
 
 
Cannot retrieve contributors at this time
Usage of Hyperimage-encoded figures in EOA publications Use of CSV files Main file: hi_figures.csv Supplemental file: hi_layers.csv Supplemental file: hi_collages.csv Coding of figures A normal figure How to code things in TEI Django file An enhanced figure How to code things in TEI Django file Figures invisible in other formats How to code things in TEI Django file Collage Subfigures Coding of references to images A normal figure How to code things in TEI Django file Links to images, with image opening in Hyperimage How to code things in TEI Django file Links to annotations on image, references to a layer How to code things in TEI Django file Links to annotations on image with text How to code things in TEI Django Links to images that only occur in Hyperimage How to code things in TEI Django file In PDF Links to Hyperimage figures Links to collages How to code in TEI Django file How it looks on a PDF Tips for the encoders General workflow Layers Data format
345 lines (269 sloc) 11.8 KB
Raw Blame
Open in GitHub Desktop

Usage of Hyperimage-encoded figures in EOA publications

Use of CSV files

Three CSV files are used, a main one that contains all necessary links, and two supplemental ones that contain additional information. The main CSV file is read by the conversion scripts to insert the Hyperimage markup.

Main file: hi_figures.csv

Structure: xmlid,hiid,layers,elementstring

  • xmlid contains the @xml:id of the figure element.
  • hiid contains the ID of that image in the Hyperimage system.
  • layers is a list of available layers for that image in Hyperimage. This overview is of rather informational character.
  • elementstring is a garbled string that contains all relevant information for Hyperimage.

Supplemental file: hi_layers.csv

Structure: hilayer,hiid,command

  • hilayer is the name of the layer.
  • hiid is the Hyperimage ID for on which the layer is found.
  • command is the plain text command.

Supplemental file: hi_collages.csv

Structure: xmlid,instruction

  • xmlid contains the @xml:id of the figure element of the collage.
  • instruction contains which images are meant to be in the collage.

Coding of figures

This is an overview of how the different figure types are tagged.

A normal figure

A normal figure shows up in all formats, in the online version, the default lightbox viewer pops up.

How to code things in TEI

<figure xml:id="chap18_fig3">
  <graphic scale="70" url="images/Schwartz_In_the_Archives_3.jpg"/>
  <head>Struan Campbell-Smith (Toronto), <hi rend="italic">Red
  Shoe</hi>, 1977, Library and Archives Canada, Accession 1980-193,
  copy negative # PA-181604, courtesy: Struanfoto, Toronto.</head>
</figure>

Django file

<EOAfigure file="imagesSchwartz_In_the_Archives_3.jpg" width="60px;" order="21" number="3">
  <caption>Struan Campbell-Smith (Toronto), <em>Red Shoe</em>, 1977, Library
  and Archives Canada, Accession 1980-193, copy negative # PA-181604, courtesy:
  Struanfoto, Toronto.</caption>
</EOAfigure>

The tag contains the attributes

  • file
  • width
  • order
  • number

An enhanced figure

The figure is displayed in all formats, but in the online version, the Hyperimage viewer is activated instead of the lightbox viewer.

How to code things in TEI

Add @type="hitrue" to the figure element. The file hi_figures.csv contains an entry with a link from the @xml:id to the annotation string. Otherwise, they look like a normal figure element.

<figure type="hitrue" xml:id="chap17_fig7">
  <graphic scale="70" url="images/Riggs_Figure7_IMG_2364.jpg"/>
  <head>Excerpt from a letter Harry Burton (Luxor, Egypt) sent to
  Nora Scott (New York), February 6, 1934, Burton correspondence
  files in the archives of the Department of Egyptian Art,
  Metropolitan Museum of Art, photo: Christina Riggs.</head>
</figure>

A line in hi_figures.csv has the following fields: xmlid, hiid, layers, elementstring

chap14_fig2,Fig142,"Fig142facade,Fig142upperfloor,Fig142capelle",ewo…fQ==

Django file

In Django, the long, encoded string is written to the value of the attribute hielement.

The tag contains the attributes

  • file
  • width
  • order
  • number
  • hielement
<EOAfigure file="imagesRiggs_Figure7_IMG_2364.jpg" hielement="ewo...Cn0="
  width="60px;" order="29" number="17.7">
  <caption>Excerpt...</caption>
</EOAfigure>

Figures invisible in other formats

A figure that is not shown in PDF and EPUB, but can be referenced there (with a comment that it's only visible in Hyperimage). That is, in PDF and EPUB there is a reference to an image that can only be seen in Hyperimage.

Special cases are Collages and Subfigures

How to code things in TEI

TEI figure elements contain @type='hionly'. Otherwise, they look like a normal figure element.

<figure type="hionly" xml:id="chap14_fig9-hi">
  <graphic scale="50" url="images/Trnkova_CAS_574.jpg"/>
  <head>The town hall in Prague’s Old Town, Andreas
  Groll, 1856, albumen print, 29.3 × 24 cm (photo), 36 ×
  33 cm (cardboard), Institute of Art History, Czech
  Academy of Sciences, collection of photographs, inv.
  no. 574, photo: Vlado Bohdan / Institute of Art
  History, Czech Academy of Sciences.</head>
</figure>

Django file

The Django construct is the same as for an enhanced figure:

<EOAfigure file="imagesRiggs_Figure7_IMG_2364.jpg" hielement="ewo...Cn0="
  width="60px;" order="29" number="17.7">
  <caption>Excerpt...</caption>
</EOAfigure>

Collage

A collage is a separate image file, two or more images stitched together. They appear online as additional images and can be called with a link.

Subfigures

Subfigures are additional figures that only show in the hyperimage layer. For example, they can be linked from other images in hyperimage.

Coding of references to images

There are also things to be observed when referencing these images.

A normal figure

The reference to a figure is done through the label of the image. This is rendered as a number in all formats.

How to code things in TEI

<ref target="#chap17_fig4" type="number"/>

Django file

In Django, the label has been resolved to a number and a link to the paragraph.

<a href="../2/index.html#14">4</a>

Links to images, with image opening in Hyperimage

In this case, instead of jumping to the image in the text, the Hyperimage viewer is opened, showing the image.

How to code things in TEI

The ref tag is used, in combination with @type='number-hi'. @target contains the ID of the corresponding figure element. This is required for the formatting of the figure number. For the Django version, the Hyperimage ID is also required. This is retrieved from the main CSV file. In TEI, the @type implies the rendition of the link as number and that the link should point to the Hyperimage viewer.

<ref target="#chap17_fig4" type="number-hi"/>

Django file

In Django, the @href points to the Hyperimage ID of that image. There is also a @class with the value HILink. The numbering is done automatically.

<a href="#Fig174" class="HILink">17.4</a>

Links to annotations on image, references to a layer

A reference to an annotated layer on an image is given. At the same time, the number of that image is to be printed. The main CSV file contains also the names of the layers. This data is in and of itself not necessary, but is a good way to keep track of the available annotations.

How to code things in TEI

In TEI, the @type implies the rendition of the link as number and that the link should point to the Hyperimage viewer. Additionally, a layer needs to be activated. This is marked by adding the @select attribute.

<ref type="number-hi" target="#chap17_fig4" select="Fig142upperfloor"/>

Django file

Like above, the @href points to the Hyperimage ID of that image, and a @class attribute with the value HILink. Additionally, @data-hilayer contains the active layer.

<a href="#Fig142" class="HILink" data-hilayer="Fig142upperfloor">14.2</a>

Links to annotations on image with text

In general, this is a variant on the above coding with the exception that the link is not the number of a figure but a piece of text. This only works properly in the online version.

How to code things in TEI

In TEI, the @type='text-hi' implies the rendition of the text as text and that the link is only visible for Hyperimage. Additionally the ref element contains text.

<ref type="text-hi" target="#chap14_fig2"
   select="Fig142capelle">Prag Rathhaus Capelle</ref>

Django

In Django, this is a link with three attributes, the hilayer points to a special annotation layer:

  • href
  • data-hilayer
  • class

Example:

<a href="#Fig142" class="HILink" data-hilayer="Fig142capelle">“Prag Rathhaus Capelle”</a>

Links to images that only occur in Hyperimage

This is a figure that is mentioned in the text and has an ID, but is only visible in the Hyperimage system

How to code things in TEI

In TEI, the @type has to be number-hionly.

<ref target="#chap14_fig5" type="number-hionly"/>

Django file

The link contains as usual the @class='HIlink' attribute. The @href links to the hiid, which is taken from the main CSV file:

<a class="HIlink" href="#Fig14239">9</a>

In PDF

The value of the figure counter is stored together with the identifier of a hionly figure. It can be inserted with \hionlyfignumber{$ID}

Links to Hyperimage figures

A link with two attributes

  • href
  • class
<a href="#Fig232" class="HILink">have never been mounted at all</a>

In contrast to the previous one, this link is lacking the link to data-hilayer.

Links to collages

In all cases, the numbers of the stitched images should not be entered manually, but put in by the usual style. These numbers have to appear in all formats. Additionally, a superordinate link exists that holds the link to the collage.

How to code in TEI

As with the @type='hitrue' case, the id given in target needs to be resolved to the Hyperimage ID.

<ref target="#chap14_coll2-5" type="hionlycollage">
  <ref target="#chap14_fig2" type="number"/> and
  <ref target="#chap14_fig5" type="number"/>
</ref>

Django file

For this representation, two separate transformations have to take place. As a first step, the references to the single images have to be resolved. Secondly, the overarching reference to the stitched image is created.

<a href="#Fig142and5" class="HILink">14.2 and 14.5</a>

How it looks on a PDF

In a PDF, just the numbers of the references should appear and should probably link to the correct images.

Tips for the encoders

To make life easy for everyone, here are some simple rules

General workflow

  • Author decides that some of the images should have some extra functionality
  • Author makes a list
  • Some images should just pop up so that users can zoom in and pan around
  • Some should have areas highlighted which can be toggled and which can be referenced from the text
  • In order not to overload the standard publication, some images are only visible in the browser, they are still referenced, though
  • Some images are less important and are subfigures to referenced online-only figures
  • Some images are to be displayed side by side so that they can be compared easily

Layers

A table should be kept, containing two columns:

  • column one: filename
  • column two: verbal description of what the markup polygon should contain

Data format

The hielement string is a base64-encoded JSON string. Its structure is

{
  "view": {
    "id": "Fig28",
    "width": 7073,
    "height": 5382,
    "title": "2.8 Verso of Fig. 2.7",
    "caption": "<b>2.8</b> Verso of Fig. 2.7: Fragment of the Artemision’s western frieze from Magnesia on the Maeander river, Carl Humann, 1891, albumen paper on cardboard mount, 21.6 x 28.5 cm (cardboard), Staatliche Museen zu Berlin, Antikensammlung, inv. no. FA-Mag04-0001, neg. no. PM 1443.",
    "author": "Julia Bärnighausen, Stefanie Klamm, Franka Schneider, and Petra Wodtke",
    "links": [
      "Fig27"
    ],
    "layers": {
      "Fig28note": {
        "color": "#0000FF",
        "title": "note",
        "points": [
          [
            0.0927470663084971,
            0.09624674842066147
          ],
          [
            0.4761770111692351,
            0.09624674842066147
          ],
          [
            0.4761770111692351,
            0.28353771832032704
          ],
          [
            0.0927470663084971,
            0.28353771832032704
          ]
        ]
      }
    },
    "files": [
      {
        "name": "origimagesANT-2a.jpg",
        "width": 7073,
        "height": 5382
      },
      {
        "name": "bigimagesANT-2a.jpg",
        "width": 1183,
        "height": 900
      },
      {
        "name": "imagesANT-2a.jpg",
        "width": 526,
        "height": 400
      }
    ]
  }
}