Most often, MEI is used for the preparation of a digital musical text based on an existing music document, or with the intention of rendering the encoded notation into a document or audio rendition. MEI can, however, be used to provide a different kind of digital reproduction of a source document, which relies on the description and provision of digital imagery. Both approaches may be combined, so that the encoding of the musical content and digital facsimiles may add different facets to the same MEI document.
This module makes available the following elements for encoding facsimiles:
These element are used to add a separate subtree to MEI, starting with the facsimile element inside music, as seen in the following example:
<mei>
<meiHead>
<!-- metadata header -->
</meiHead>
<music>
<facsimile>
<!-- The facsimile subtree starts here. -->
</facsimile>
<body>
<!-- The encoding of the musical content goes here. -->
</body>
</music>
</mei>It is possible to have more than one facsimile element in this location. This is especially useful when multiple sources are encoded in the same file using the mechanisms described in chapter Editorial Markup of these Guidelines. In this case, the @decls (declarations) attribute of facsimile may be used to refer to a source defined in the document’s header, as seen in the following example:
<meiHead>
<source xml:id="facsimile.source1">
<!-- description of source -->
</source>
</meiHead>
<music>
<facsimile decls="#facsimile.source1">
<!-- facsimile content -->
</facsimile>
</music>Within a facsimile element, each page of the source is represented by a surface element. Each surface may be assigned an identifying string utilizing the @label attribute. In addition, it may encapsulate more detailed metadata about itself in a figDesc element. The coordinate space of the surface may be recorded in abstract terms in the @ulx, @uly, @lrx, and @lry attributes. For navigation purposes, surface has a @startid attribute that accommodates pointing to the first object appearing on this particular writing surface.
<facsimile>
<surface label="page 1" lrx="2000" lry="3000" startid="#measure1" ulx="0" uly="0"></surface>
</facsimile>Within surface elements, one may nest one or more graphic elements, each providing a reference to an image file that represents the writing surface. Multiple graphic elements are permitted in order to accommodate alternative versions (different resolutions or formats, for instance) of the surface image. In spite of changes in resolution or format, all images must contain the same content, i.e., the entire writing surface.
<facsimile>
<surface>
<graphic height="2000" target="image1.jpg" unit="px" width="3000"></graphic>
<graphic height="1000" target="image1smaller.jpg" unit="px" width="1500"></graphic>
<graphic height="200" target="image1smallest.png" unit="px" width="300"></graphic>
</surface>
</facsimile>The preceding markup will provide the basis for most page-turning applications. Often, however, it is desirable to focus attention on particular areas of the graphical representation of the surface. The zone element fulfills this purpose:
<surface lrx="3000" lry="2000" ulx="0" uly="0">
<graphic height="2000" target="image1.jpg" unit="px" width="3000"></graphic>
<zone lrx="370" lry="410" ulx="300" uly="200"></zone>
<zone lrx="439" lry="410" ulx="367" uly="200"></zone>
<zone lrx="512" lry="410" ulx="436" uly="200"></zone>
</surface>The coordinates of each zone define a space relative to the coordinate space of its parent surface. Note that this is not necessarily the same coordinate space defined by the width and height attributes of the graphic that represents the surface. The zone coordinates in the preceding example do not represent regions within the graphic, but rather regions of the writing surface.
Because the coordinate space of a zone is defined relative to that of a surface, it is possible to provide multiple graphic elements and multiple zone elements within a single surface. In the following example, two different images representing the entire surface are provided alongside specification of two zones of interest within the surface:
<surface lrx="3000" lry="2000" ulx="0" uly="0">
<graphic height="2000" target="image1.jpg" unit="px" width="3000"></graphic>
<graphic height="1995" target="image1cropped.jpg" unit="px" width="2995"></graphic>
<zone lrx="370" lry="410" ulx="300" uly="200"></zone>
<zone lrx="30" lry="30" ulx="0" uly="0"></zone>
</surface>A zone element may contain figDesc or graphic elements that provide detailed descriptive information about the zone and additional images, e.g., at a different/higher resolution, of the rectangle defined by the zone. The data objects contained within the zone may also be specified through the use of the @data attribute, which contains ID references to one more elements in the content tree of the MEI file, such as a note, measure, etc.
<!-- In the facsimile subtree: --><zone data="#facsimile.measure1" xml:id="facsimile.zone1"></zone>
<!-- somewhere in the content: -->
<measure xml:id="facsimile.measure1">
<!-- measure content -->
</measure>Conversely, an element in the content may refer to the facsimile subtree using its @facs attribute, which is made available by the att.facsimile attribute class. The last example could therefore be encoded with pointers in the other direction:
<!-- In the facsimile subtree: --><zone xml:id="facsimile.zone2"></zone>
<!-- somewhere in the content: -->
<measure facs="#facsimile.zone2" xml:id="facsimile.measure2">
<!-- measure content -->
</measure>The pb element defined in the Shared Elements, Models, and Attributes makes special use of the @facs attribute, in that it does not point to a zone, but a surface element instead. A pb marks the beginning of a page, so it can be concluded that all elements in the content tree which are encoded between any two pb elements encode musical symbols written on the page ( surface) referenced by the first of these two pb element’s @facs attribute.