Loading external images

Section 3.13 Loading external images

Some diagrams may need to import an external image and then add some features. For instance, one may want to load a topographical map and add a vector indicating the gradient of the elevation function. PreFigure supports importing PNG, JPEG, GIF, and SVG images with the <image> element. Figure 3.13.1 and the accompanying source Listing 3.13.2 demonstrate.

🔗

Figure 3.13.1. This diagram contains a PNG image that is loaded from an external file. Image courtesy of the United States Geological Survey.
🔗

Listing 3.13.2. The PreFigure source for Figure 3.13.1.

🔗

<diagram dimensions="(300,300)" margins="5"
         xmlns="https://prefigure.org">
  <coordinates bbox="(0,0,10,10)">
    <image lower-left="(0,0)" dimensions="(10,10)"
           source="images/wasatch.png" opacity="0.6">
      <label anchor="(0,10)" alignment="se">
        A topological map with a vector
      </label>
    </image>
    <definition>tail=(4.6,5.6)</definition>
    <vector tail="tail" v="(2,2.5)" stroke="blue"/>
    <point p="tail"/>
  </coordinates>
</diagram>

The @source attribute is the name of the file that contains the image. Finding this image file in the local file system is handled in the same way that external data files are found, as described in Subsection 3.12.1. That is to say, if there is a PreFigure publication file, then the value of the attribute @directories/data is prepended to the value of the @image/source attribute. For instance, if @source="images/my_image.jpg" and @directories/data="/home/user/projects/", then PreFigure will expect the image file to be in /home/user/projects/images/my_image.jpg".

🔗

If @directories/data is not given in a PreFigure publication file, then the value of @source is interpreted relative to the PreFigure source file.

🔗

Within a PreTeXt project, the value of @docinfo/data should be a directory that contains the image file, possibly in a sub-directory as indicated by the value of @image/source. For example, if @source="images/my_image.jpg" and @docinfo/data="/home/book/source/data", then the file should live at /home/book/source/data/images/my_image.jpg. (Of course, one would not likely give an absolute path in @docinfo/data.)

🔗

PreFigure attempts to identify the image format from the file name’s suffix. For instance, image.gif is assumed to be a GIF. If the file name suffix does not properly denote the image type, include the attribute @filetype, whose value can be "svg", "png", "gif", "jpg", or "jpeg".

🔗

The location and sizing of the image is determined by a rectangle defined through the attributes @center, @lower-left, and @dimensions. Only one of @center and @lower-left needs to be given. The image will be scaled in such a way so as to preserve its aspect ratio and to fit inside the rectangle.

🔗

Additional attributes include @rotate, which defines an angle, epxressed in degrees, by which the image is to be rotated about its center. The attribute @scale can be either a single number or an ordered pair to scale by different amounts horizontally and vertically. Scaling is not strictly enforced, however, since the image is already scaled to fit inside the prescribed rectangle. What may be most useful is @scale="(-1,1)" to flip the image. Finally, @opacity gives a value for the opacity to use when including the image, as demonstrated in Listing 3.13.2.

🔗

Caution.

Because PreFigure prioritizes accessible diagrams and imported images will likely not render well in an embossed tactile format, an <image> element must include elements intended to replace the image in a tactile diagram. Notice that the <image> in Listing 3.13.2 contains a label with a brief description.

🔗

Figure 3.13.3 illustrates a PreFigure version of a diagram from the PreTeXt sample article.

pretextbook.org/examples/sample-article/html/section-graphics.html#figure-shark-attack

Notice how the image of the shark is scaled to flip it horizontally. A rectangle is also drawn around the swimmer to illustrate how the image is scaled to fit inside its rectangle (and to protect the swimmer from the shark). Finally, note that the tactile replacements for these images each consist of a labeled point showing the location of the shark and the swimmer. Thanks to Stephen Brown for permission to reproduce this image.

🔗

Figure 3.13.3. This diagram loads two images, one for the shark and one for the swimmer.
🔗

Listing 3.13.4. The PreFigure source for Figure 3.13.3.

🔗

<diagram dimensions="(540, 240)" margins="5"
         xmlns="https://prefigure.org">
  <coordinates bbox="(0,0,9,4)"> 
    <rectangle lower-left="(8,0)" dimensions="(1,2)"
               fill="yellow" stroke="none" fill-opacity="0.3"/>
    <path start="(0,0)" closed="yes" fill="lightsteelblue">
      <lineto point="(0,2)"/>
      <lineto point="(8.1,2)"
              decoration="ragged; step=7; offset=4; seed=1"/>
      <lineto point="(8.1,0)"
              decoration="ragged; step=7; offset=4; seed=1"/>
    </path>
    <image center="(1.5,1)" dimensions="(3,1)"
           source="images/shark.png" scale="(-1,1)">
      <point p="(1.5,1)">
        Shark
      </point>
    </image>
    <image center="(5,1)" dimensions="(1,2)"
           source="images/swimmer.png">
      <point p="(5,1)">
        Swimmer
      </point>
    </image>
    <rectangle center="(5,1)" dimensions="(1,2)"
               dash="9 9" stroke="gray"/>
    <line endpoints="((1.5,3),(8,3))" stroke="black"/>
    <tick-mark location="(1.5,3)" size="(5,5)"
               alignment="n" offset="(0,4)">
      <m>70 \mathrm{ m}</m>
    </tick-mark>
    <tick-mark location="(5,3)" size="(5,5)"
               alignment="n" offset="(0,4)">
      <m>50 \mathrm{ m}</m>
    </tick-mark>
    <tick-mark location="(8,3)" size="(5,5)"
               alignment="n" offset="(0,4)">
      <m>0 \mathrm{ m}</m>
    </tick-mark>
  </coordinates>
</diagram>

🔗

Prev Top Next