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
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
```xml
<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
```xml
<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.
```xml
<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`
```csv
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
```xml
<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.
```xml
<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](#an-enhanced-figure):
```xml
<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
```xml
<ref target="#chap17_fig4" type="number"/>
```
### Django file
In Django, the label has been resolved to a number and a link to the paragraph.
```xml
<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.
```xml
<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.
```xml
<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.
```xml
<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.
```xml
<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.
```xml
<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:
```xml
<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`.
```xml
<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:
```xml
<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
```xml
<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.
```xml
<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.
```xml
<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
```json
{
"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
}
]
}
}
```