Simulation Model Icon Animations

This document describes one method of attaching icons to objects. See Icons for a general description of all methods.

Instead of animating graphical simulations by simply highlighting the rectangular boxes with colors, you can replace the boxes with arbitrary drawings, -or actual images-, of meaningful objects.
You can do this with the following built-in routines:

CSIM_READ_IMAGE - Reads an image into an image data structure.
CSIM_SET_IMAGE_ICON - Replaces a named box on your diagram with an image. You use it similar to the highlight_box() function.
display_image_resizable - Replaces a named box on your diagram with an image that can be moved or displaced around the screen.

You can graphically show your components in various states by preloading images depicting each state into different image variables at start-up. Then change the component's image according to its state.

A set of network-related icon images is provided with every CSIM distribution under csim/model_libs/icons. You can set your boxes to be displayed in the GUI as an aribtrary icon, by naming an image file under the Properties / Attributes / Icon dialogue.

The following is a detailed description of the image-display routines:

struct rs_image *CSIM_READ_IMAGE( char *fname ) - This routine accepts the name of a file containing an image in ascii PPM or binary image (BIM) format. PPM is a convenient ascii-text file format for images. GIF and JPG images can be converted to PPM via widely available utilities such as: XV, The Gimp, cjpeg, netpbm, ..., etc.. ASCII PPM images can be converted to more compact binary images (.bim) through the ppm2bim utility found in the tools/platform/general_utiltites directory of every CSIM distribution.
The CSIM_READ_IMAGE routine returns a pointer to the image. Use as, for example:
```
	struct rs_image *image_ptr;

	image_ptr = CSIM_READ_IMAGE( "imagefile.ppm" );
```
Image file names must end in either the .ppm or .bim suffix.
void CSIM_SET_IMAGE_ICON( char *obj_name, struct rs_image *image_data ) - This routine accepts an object-name in your diagram, and a pointer to an image, and it displays the image at that object location; on-top of the object's box. Regardless of the actual size of the original image, the image is automatically resized to fit the size of the box. The image is persistent, in that any redrawing of the display, such as due to zooming, panning, or navigating, will preserve the image.
Example:
```
	CSIM_SET_IMAGE_ICON( "/platoon1/radio8", image_ptr );
	
```
The original or default image is restored by calling CSIM_SET_IMAGE_ICON with a null image value.
void display_image_resizable( char *obj_name,
struct rs_image *image_data,
float xoffset, float yoffset
)
- This routine accepts an object-name in your diagram, and a pointer to an image, and it displays the image at that object location; on-top of the object's box. Regardless of the actual size of the original image, the image is automatically resized to fit the size of the box.
The xoffset, and yoffset parameters enable you to specify a screen location for the icon to appear relative to the named box. This allows you to place animations adjacent to a box, or to effectively move the box's symbol around the screen. Normally, you would use a (0.0, 0.0) offset, which places the image's top-left corner at the top-left corner of the box. Positive offsets will move the image down or to the right, respectively.
The image will not be persistent. That is, any zooming or panning will erase the image.
Example:
```
	display_image_resizable( "/platoon1/radio8", image_ptr, 0.0, 0.0 );
	
```
See also Fixed Size Images for non-resizable image routines. These routines will not resize the images based on zoom level. I.E. One pixel of original image - equals - one pixel on display image.