== <image> ==

An image object represents some photographic image.  On the input side, it should be treated as an input to an image manipulation algorithm.  Some older programs use this to display a diagram for control values, although it is better to use a [wiki:rp_xml_ele_note note] for that.  The image data is stored within the {{{<current>}}} tag as a base64-encoded GIF, JPEG, or PNG image.  You can use your favorite language's equivalent '''Rappture::RpLibrary::putFile''' function to automatically load an image file into your Rappture library object or you can take advantage of the '''Rappture::encoding''' module to do the base64-encoding. Also, on Linux, you can use the '''{{{base64}}}''' or '''{{{mimencode}}}''' program to convert a normal GIF/JPEG/PNG file to the proper encoding shown below:

[[rpimage(zoo_image1.gif)]]
{{{
  <image>
    <current>R0lGODlhtAA8APcAAFeBu////0VurKW829Ld7YSjzWKJwLzN5HmayfT3+unu9sfV6G2SxJqz1t3m
8Y+r0rHE31aAus3Y6VJ5sEpysEdvrXeVwlV+uVB6tVZ/uEhwrlV/uEx1slN8t1eAuk50qFF4rlJ7
tkZol5yy0092q0dqmVV+t053tElxr0VmlEVnlU92qlR8tFN7sk12s0VtrEVtqkRrpktvoUxxpEt0
...
    </current>
  </image>
}}}
An image can have a label in the {{{<about>}}} section.  In that case, the actual image is scaled down to thumbnail size, and information about the image is presented to the right of it, as follows:

[[rpimage(zoo_image4.gif)]]

[[BR]]
Another option for image objects is <resize>, which determines the size of the thumbnail presented.  Users can set the size of the preview thumbnail by including this tag in the <image> object as shown in the examples below. If the <resize> parameter is set, then the image is resized. The value "auto" or "none" resizes to a default 100x100 thumbnail.  The "width=XX" or "height=xx" form resizes to a particular size.

{{{
  <image>
    <resize>height=60</resize>
    <current>R0lGODlhtAA8APcAAFeBu////0VurKW829Ld7YSjzWKJwLzN5HmayfT3+unu9sfV6G2SxJqz1t3m
8Y+r0rHE31aAus3Y6VJ5sEpysEdvrXeVwlV+uVB6tVZ/uEhwrlV/uEx1slN8t1eAuk50qFF4rlJ7
tkZol5yy0092q0dqmVV+t053tElxr0VmlEVnlU92qlR8tFN7sk12s0VtrEVtqkRrpktvoUxxpEt0
...
    </current>
  </image>
}}}
{{{
  <image>
    <resize>width=40</resize>
    <current>R0lGODlhtAA8APcAAFeBu////0VurKW829Ld7YSjzWKJwLzN5HmayfT3+unu9sfV6G2SxJqz1t3m
8Y+r0rHE31aAus3Y6VJ5sEpysEdvrXeVwlV+uVB6tVZ/uEhwrlV/uEx1slN8t1eAuk50qFF4rlJ7
tkZol5yy0092q0dqmVV+t053tElxr0VmlEVnlU92qlR8tFN7sk12s0VtrEVtqkRrpktvoUxxpEt0
...
    </current>
  </image>
}}}
{{{
  <image>
    <resize>none</resize>
    <current>R0lGODlhtAA8APcAAFeBu////0VurKW829Ld7YSjzWKJwLzN5HmayfT3+unu9sfV6G2SxJqz1t3m
8Y+r0rHE31aAus3Y6VJ5sEpysEdvrXeVwlV+uVB6tVZ/uEhwrlV/uEx1slN8t1eAuk50qFF4rlJ7
tkZol5yy0092q0dqmVV+t053tElxr0VmlEVnlU92qlR8tFN7sk12s0VtrEVtqkRrpktvoUxxpEt0
...
    </current>
  </image>
}}}

[[BR]]
If the {{{<convert>}}} option is included, it specifies a format that the image should be converted to when passed to the underlying program.  For example, suppose the underlying program expects all images in GIF format.  If you add {{{<convert>gif</convert>}}} to your input specification, then all images will be passed along in GIF format, regardless of whether they were uploaded as PNG, JPEG, etc.  Use the {{{<convert>}}} tag in your input specification as follows:

{{{
  <image>
    <about><label>Input image</label></about>
    <convert>gif</convert>
  </image>
}}}

Other valid image formats for the {{{<convert>}}} tag are:  {{{bmp}}}, {{{gif}}}, {{{ico}}}, {{{jpeg}}}, {{{pcx}}}, {{{pixmap}}}, {{{png}}}, {{{pgm}}}, {{{ppm}}}, {{{ps}}}, {{{pdf}}}, {{{sgi}}}, {{{sun}}}, {{{tga}}}, {{{tiff}}}, {{{window}}}, {{{xbm}}}, {{{xpm}}}.

[[BR]]
An image can also be produced as output.  In that case, the image appears in a viewer with controls for zooming in and out:

[[rpimage(zoo_image2.gif)]]
{{{
  <output>
    <image id="outi">
      <about>
        <label>Rotated Image</label>
      </about>
      <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwh
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAAR
...
      </current>
    </image>
    ...
  </output>
}}}



You can also add a little html note to your image to help explain it's meaning:

[[rpimage(zoo_image3.gif)]]

The xml would look like this:
{{{
  <image>
    <current>R0lGODlhtAA8APcAAFeBu////0VurKW829Ld7YSjzWKJwLzN5HmayfT3+unu9sfV6G2SxJqz1t3m
8Y+r0rHE31aAus3Y6VJ5sEpysEdvrXeVwlV+uVB6tVZ/uEhwrlV/uEx1slN8t1eAuk50qFF4rlJ7
tkZol5yy0092q0dqmVV+t053tElxr0VmlEVnlU92qlR8tFN7sk12s0VtrEVtqkRrpktvoUxxpEt0
...
    </current>
    <note>
        <contents>html://&lt;p style="text-align: center;"&gt;
                  Check out the rotation of this image!&lt;/p&gt;</contents>
    </note>
  </image>
}}}

You can see working code in the [browser:trunk/examples/zoo zoo of examples] in the [browser:trunk/examples/zoo/image image example] or on the hub in the directory /apps/rappture/examples/zoo/image.