_______________________________________________________________________________ BEFORE YOU BEGIN Please read the README.FIRST file - found at the root level of this server - for general information and instructions on unarchiving and uncompressing files (files with the ".sit", ".hqx", ".zip", ".tar", and ".Z" extensions). The README.BROCHURE also contains helpful descriptions of this and other software offered on the ftp server. _______________________________________________________________________________ INSTALLING COLLAGE Collage is available in executable form the anonymous ftp server ftp.ncsa.uiuc.edu. New versions may be picked up from there. Platforms supported include: Sun Sparc (SunOS) IBM RS6000 (AIX) DEC DECstation (Ultrix) DEC Alpha (OSF/1) SGI (IRIX) HP 700 series (HP/UX) --------------------------L I N U X--------------------------------- ---> And now a very Alpha Linux port <--- ---> (Send mail to Elie Mourad mourad@three.dts.harris.com <--- ---> for comments) <--- ---> BUGS: Contour drawings fails. <--- -------------------------------------------------------------------- You will need both the collage executable and the collage_server executable. After downloading them by ftp in binary mode, move the collage and collage_server executable to a directory within your $PATH. When you download the server executable, it will be under the name server.machinetype (Example server.sn4). Since the collage_server is started up by collage, the server needs to be called something that collage can find it by. Rename the server to 'collage_server'. Make sure that the executables are given execute permission after downloading. This is done with the chmod command. Ex 'chmod 755 collage server' STARTING COLLAGE Collage is an X window based tool. If you know how to start up an X based tool, you can skip this section. Also, if you plan to run Collage on the same machine that your X server is running on, you can skip this section. To start up an X window based tool, the user must first tell the X server to allow clients from the machine your are running your client on. If your X display is a workstation, you can do this by executing 'xhost +hostname'. Where hostname is the name of the machine that you will be running the X window tool on. On the client machine you need to specify where the X server is running. If your X server's name is 'yoyodyne' then you will type: from csh: 'setenv DISPLAY yoyodyne:0' or from sh or ksh: 'DISPLAY=yoyodyne:0' 'export DISPLAY' See your local system administrator for details on running X applications. Type 'collage'. The collage main window should appear on your X display and then a splash screen will appear for a couple seconds and disappear while the tool is initializing. If this does not happen, check your X DISPLAY variable (above). STARTING A COLLABORATIVE SESSION: A collaborative session is started by one person clicking clicking on the main window menubar option 'Collaborate/Begin Session'. This causes a dialog box to pop open allowing the user to type in a server DTM port. A DTM port is of the format: [host]:port_number Where host is the name of the machine of the DTM port and port_number is some number between 2048 and 65535. Pick some random number for a port number and type it in so long as it is between 2k and 64k. The host part is not necessary when the port is on the local machine. This will always be the case when starting the server. So type something in like :2345 as your Server Port. People may join the collaborative session just started by selecting 'Collaborate/Join Session' on their collage main window. They will need to fill in the box that says 'Connect to server'. In this box, they should type the DTM port that was selected for the server. Example: Bill and Ted want to collaborate. They each start up collage by typing 'collage'. Bill is running this on a machine called 'yoyodyne'. Bill selects 'Collaborate/Begin Session'. In the "Server Port" box Bill types in ":2345". Bill then selects 'OK' on the dialog box and the server is launched and a dialog box pops up saying 'Just established a connection with collab server'. On Ted's main window, he selects 'Collaborate/Join Session'. In the 'Connect to Server' box, Ted types "yoyodyne:2345". Ted then selects the 'OK' button and is connected up to the collab server. If Ned wants to join the session, he does the same thing as Ted. From here on everything done is shared with all the other collaborators. LOADING DATA OBJECTS: To load a single data set, click on the Load function located in the File menu. The tool opens up a motif file selection box. The user specifies the file that is to be loaded. The user may select a file by first specifying the directory and then double clicking on the file. If the file is an HDF file, the HDF browser window will open. From the HDF browser the user may select which data object is to be loaded. The data object is selected by double clicking on the desired HDF data object. If multiple objects are to be loaded the user may select them by first clicking on the desired objects and then dragging or by holding the key and clicking on the next object. When all objects are selected, they may be loaded by clicking on the "Send Selection" in the Transport menu. SUPPORTED FILE TYPES: HDF RIS8 (raster images) SDS 2d & 3d (scientific data sets) PAL (palettes) GIF Graphic Interchange Format XWD X Window Dump ASCII text OPERATIONS: Once a data set is loaded, several data analysis operations may be performed on it. These include color histogram graphs, XY profile plots, and color contour overlays. To produce a histogram, select the dashed square in the upper left hand corner of the data set window. This puts the cursor in region selection mode. Now select an area on the image that you wish to see a histogram of. This is done by clicking the upper left hand corner of the rectangular region and while the mouse button is held down dragging the mouse to the lower right hand corner of the region. When the mouse button is released a color histogram plot will open up on each of the collaborators screen. The histogram may be changed by repeated the selection process. An XY profile plot may be produced by selecting on of the dash line boxes in the upper left hand corner of the image window. This puts the cursor in a line selection mode. Click the mouse on the image and then drag the mouse to the end point of the line. When the mouse button is released, a profile plot will appear. This profile plot may be changed by repeating the selection process. Anotations on the image may be done by selecting one of the drawing icons on the left and side and then drawing with the mouse on the image. Color may be selected by clicking on one of the nine arrayed color cells on the lower left hand corner of the image. The color cells may be changed to any colors within the color bar (extreme left side) by sliding the triangle along the color bar. The Image/Options menubar allows the user to select different pen widths to draw in. WHITEBOARD: The whiteboard in collage is synonymous with a physical whiteboard. multiple participant may draw on the whiteboard at the same time with different color markers. The whiteboard may be invoked by clicking on the main menubar in Tools/Whiteboard. The whiteboard will appear on the other participants display when a user draws in it. A user may draw in the whiteboard by selecting on one of the drawing tools in the upper left hand corner of the whiteboard window. The pencil icon will allow the user to draw in a free hand mode similar to a pencil. The diagonal line will draw a line. same for the oval, rectangle, and arrow. The toggle with the letter 'A' allows the user to type in text. A user Simply clicks on the toggle and then in the whiteboard to place the cursor. Text typed in from the keyboard will then appear on the whiteboard. Note, backspace (delete) does not work on text in the whiteboard. A pen width may be selected for drawing in the whiteboard. This is done by selecting a pen width in the options menu of the whiteboard. Pen color may be selected several ways. In the lower left corner of the whiteboard is a set of 9 color selection buttons. A user may click on one of these colors to change the color that he will draw in. Since collage support 8-bit color displays, there is actually 256 colors that are available to be displayed at any one time. A user may chose anyone of these 256 by setting it to one of the 9 color selection buttons. A user simply clicks on the select button to set. Along the left side of the whiteboard is a color bar where all 256 colors are displayed. When the user clicks on one of these colors, it is then inserted into the selected color selection buttons. There are two toggle buttons for erase. The one on the left is a free hand erase. The mouse cursor turns into a block eraser. To erase a portion of the whiteboard, simply click and drag the mouse over are to be erased. The eraser on the right is an area erase. A user may rubber band box an area on the whiteboard. This is done by clicking in one corner of an area to be erased and dragging the mouse to the opposite corner and then releasing the mouse. When the mouse is release the area selected will be cleared. There is also a clear whiteboard erase which will remove everything from the whiteboard. This button is located in the whiteboard menu under the menu button Edit/Clear Whiteboard. This whiteboard supports screen captures inserted onto the whiteboard. This is useful if the user would like to incorporate something on his screen into a drawing. To do this, click on the Edit/Copy button in the Whiteboard menubar. When the button is released, the cursor will change to the area selection cursor. Select a portion of the screen to be captured by rubberband boxing both corners. To paste it into the whiteboard, click on the Edit/Paste button in the Whiteboard menubar. Next, the user should click on the location in the whiteboard that he would like the copied image to appear. An 8-bit pseudo color system can only display 256 colors out of all the colors that exist in the world at one time. This set of 256 colors is referred to in collage as a palette. Most loaded images have a palette associated with it. Collage also supports a palette editor for creating new palettes. The whiteboard allows the user to use any one of the palettes that have been loaded into the session as the set of colors for drawing in the whiteboard. This may be done by selecting the Edit/Use Palette option in the Whiteboard menubar. Each palette has 256 colors. Out of these colors, the X display uses some of these for things like window borders, backgrounds, xterm, etc. Collage is concerned with the colors used for it's controls. These colors are allocated in the system palette which may be different from the palette used for displaying images. Sometime there is a conflict with these palette entries. By default, colllage will use the entire palette associated with an image and then put back the lower 30 colors of the system palette. This is an attempt to preserve the motif colors as well as colors used by other applications sharing the system palette. This number 30 may be set at start up time in the user's .Xdefaults. The resource name for this is BasePixel. So, to change this number to 48, in one's .Xdefaults, one would have a line like: collage*BasePixel: 48 With some images, this may drastically affect the way the image is viewed especially if a large portion of the image uses the low end values. In the Collage provides a method to use the entire palette associated with an image. This option may be turned on from the Edit/Use Entire Palette toggle. This toggle swaps out the system color map and restores the lower range of colors to the palette. This may have the affect of making the Motif control panel difficult to see while color map focus is on the window. Turning off this toggle will restore the colors for this window. PALETTE EDITOR: The palette editor is used to create or alter palettes. To open the palette editor, click on the Windows/Palette Editor toggle from the main window menubar. As described above, a palette is a set of 256 colors which is a subset of all possible colors (16,777,216). The palette editor allows the user to change this subset of colors. The palette editor has several ways of doing this. Collage may have multiple palette loaded up at any time. These palettes may be associated with images that have been loaded up. From the palette editor, the user may select a palette to edit by clicking on the named palette in the View menubar from the palette editor window. Once clicked on, this palette will then be loaded ready to be edited. Clicking on the fiddle button will through the user into a fiddle mode. In fiddle mode, the mouse is restricted to movements within the palette window. Mouse movements are tracked and make realtime changes to the palette. Vertical movements of the palette perform a linear expansion and compression on the palette. Horizontal movements will shift the colors to the left or right. Clicking on the mouse button will end the fiddle mode. This feature is primarily for data analysis. The dynamic nature of this tool allows the user to easily shift the colors to get the most color contrast out of a portion of an image of greatest interest. Color rotation may be performed by clicking on the color bar and moving the mouse horizontally. The palette editor support color component maniupation. This may be done in one of three color models: 1) red,green,blue; 2) cyan, magenta, yellow; hue, saturation, value. The controls for the color components are in the lower left corner of the palette editor. The color components may be displayed by clicking on the corresponding square toggle. Clicking on the diamond toggle will allow the user to change this component. Multiple color components may be displayed, but only one component may be manipulated at a time. Once a color component is selected for change, simply redraw the color component in the color component display window ( just below the color bar). The upper region represents higher values. As the components are changed, the palette is updated. Manipulating the color components is a quick way to add new color to a range of the palette. Other color models may be selected using the option toggle menu bar above the color component selection toggles. In a collaborative session, the palettes are sent to the other participants when the a manipulation is completed. For example, while doing the fiddle, the palette isn't sent until the user exits fiddle mode. When manipulating a color component or rotating the palette, updates are sent over when the mouse button is released. The 'Save As' button in the palette editor will save the palette to an HDF file. PUBLISH / PRIVATE COPY Within collage it is possible to have a private copy of an image that only the owner can see and operate on. This may be done by either loading up a data set before establishing a connection with other collaborators, or clicking on the File/Private Copy button in the menubar to make an image/whiteboard private. If an image is private, it may be made public by clicking on the File/Publish button in the menubar. This will send the image to all of the participants in the session. PRINT The print command in collage allows a user to print an image or text of the window from where the window it was invoked. In the case of an image, a PostScript file is generated in either Color or Greyscale. The user has the option of sending this to the printer or saving it as a file. If a special print command is need for a particular system, it may be specified in the print dialog box. SAVE In the case of a whiteboard or image, the save option will save the data file from the window from which it was invoked into an HDF file. In the case of a text window, the text will be saved as an ASCII file. CLOSE The close button is like a stow button. The data displayed in the window from wich the close was invoked is not removed but taken from sight. The window may be restored from the main collage window menu option 'Windows'. SCREEN CAPTURE The screen capture capability of collage is a very useful tool for showing other participants other applications that are running on ones screen. The screen capture will grab a selected portion of the users screen and send it as a raster image to the other participants. This raster image may then be annotated in the same fashion that images or whiteboard may be. This function is invoked from the main collage window under the menu Tools/Screen Capture. Once this menubutton is clicked, the cursor turns into the area selection cursor. The user then clicks on one corner of the are that he would like to select and then drags the mouse to the opposite corner (rubber band boxing) and then releases. When the mouse button is released, the image is sent to the other participants including the person who sent it. CHAT BOX The Chat Box is used for communicating with other users by typing. Although it is recommended to use collage with a telephone, the chat box may be used when the use of a telephone is not an option. The chat box may be opened from the Tools/Chat Box menu button in the main menu box. Or, it will open automatically when another participant sends a message. Messages are sent by typing them in the 'Input:' box of the chat box. The messages are sent when the user hits . The 'Chat Session:' box displays a log of all the messages sent in the session. Each line of a message is preceded by the person's name who sent the message. ANIMATIONS An animation consists of a sequence of image viewed over time similar to a video. An animation file may be loaded up from the collage man window File/Open Animation menu button. Collage supports animations of multiple 2d frames stored in an HDF file. Collage also supports animating through a 3d cube of data. The user should first select the type of animation desired. This is done in the Options menu of the main collage window. Collage supports three type of animations. The choice is made based on the resources of the machine the user will be viewing the animations and the size of the animation. The Option/Animate from server memory will cause the frames of the animation to be read in and sent over to the X Window server and stored locally on the server side. This type of animation is by far the fastest since no transfer time is required between flipping to the next frame. However, it also consumes enough memory on the X server to store the entire animation. This may not be an option with some X servers that have small amounts of memory. The Option/Animate from memory will cause the frames to be read in and stored in the collage client memory. This options save the time of having to read in each frame before being displayed, but there is a delay when the image is sent to the X server. The last option Option/Animate from disk tells collage that when it is animating, it will read each frame from disk and then send it over to X server to be displayed. This option is the slowest but also consumes the least memory resources. This option is ideal for extremely large animations. To load an animation, the user first selects the file to be animated. After the file has been selected, the HDF file browser will open. In the case of multiple 2d frames, the user will need to select all of the frames to be animated. This is best done by clicking on the Raster Image Group toggle (RIG) on the left. This will filter out the HDF objects the HDF file so that only the raster image groups are displayed. Click and drag so that all of the images desired are selected. If the user desires to skip some frames, he may hold down the control button while selecting the objects with the mouse. When all of the raster image frames are selected, click on the Transport/Send Selection menubutton in the HDF browser menubar. The animation window will then appear and the frames will be displayed as the animation is loaded into memory and sent to the other collaborators. The animation controls work much like a video casette recorder or CD player. There is a play button (the triangle), a pause button (to vertical parallel lines), a single frame step (triangle with a bar). There is also a reverse play and reverse single step denoted by a triangle in the reverse direction. Below these controls is a horizontal scroll bar which shows the user where in the animation the current frame is. The user may grab this scroll bar with the mouse and move further into the animation or back. In the lower right is a vertical scroll bar which controls speed of play. In the Options menu of the animation window contains options for type of animation play. By default the animation is a 'Single Run' animation which means that the animation will stop when it gets to the end. The user may set this to a 'Continuous Wrap' where the animation loops back to the beginning when it reaches the end, or set this to a 'Continuous Bounce' where the animation will play in reverse when it reaches the end. Also in the Options menu is a toggle for displaying the frame number on the animation. The frame number will appear in the lower left corner. While in a collaborative session, the animations are only synchonzied at certain points. When the animation starts, stops, or single frame advances, all collaborators are viewing the same frame. Also, all collaborators will be viewing the same type of animation (ie Single Run, Continuous Bounce, or Continuous Wrap). Animations will be played at the fastest speed possible or selected for each display. This means that faster machines will be able to run through the animation quicker. All participants are synchronized to the same frame when the animation stops. TEXT EDITOR Collage supports a simple text editor which is designed to collaboratively edit a text file with other participants. Because use of particular text editor borders on religious issues, there was no attempt made in making an editor that people would want to develop documents in. The text editor supports sharing of highlights. This is a useful feature for pointing out paragraphs in the text. Scrolling is done independently from other participants so that each user may read a different part at a time. Scrolling is synchronized when a portion of text is selected. Changes to the text may be done by any of the participants. One note: the text editor does not yet have a locking mechanism. It is necessary for only one person to be editing at a time or else the text source may get out of synch. The text editor does support the drawing functions mentioned in the whiteboard section of this document. Drawings appear in the overlay play and do not affect the text. Further, as of release 1.2 drawing in the text overlay plane is only supported on the Unix/X versions (not Mac or PC). COMMAND LINE ARGS FOR COLLAGE: -load filename [filename ...] when collage is started up, it will load up the specified file(s). In the case of a GIF or XWD file, it will load up the first image. In the case of an HDF file, if ther is only one image, it will load this image up into the single image display. If there are multiple images, it will load them all into the animation window. -DTMIN host:port specifies a DTM in port. -DTMOUT host:port specifies a DTM out port. This may be used to connect to the collage_server on start up rather than specifying it through the menu interface. COLLAGE INTERNALS: DTM: Collage uses the DTM (Data Transfer Mechanism) as it's protocol for communicating over the network. In a collaborative session collage communicates with other collage clients via the collage server. Other clients such as data analysis tools, simulations may send data to the collage session to be viewed. The following assumes the reader has a programming level understanding of the DTM library. Documentation for DTM as well as source may be found on the NCSA anonymous ftp server ftp.ncsa.uiuc.edu. The following information is for those who wish to send collage data. A collage client has one DTM inport and one DTM outport. These ports may be specified at startup time with the command line args -DTMIN :port/-DTMOUT host:port. When collage connects to a remote process via DTM it will handshake with an SRV class message. The SRV message class is for establishing a connection within a collaborative session. The "message is, "I'm connecting to you, here is my userID, and my inport". When the server receives this connection, it will be on it's global inport. The server sets up a separate inport and outport for each client. The return message from the server will be "ok, change your outport to this address". The new address passed back will be a special inport on the server just for reading incoming messages from this client. The client will then close it's outport to the server and then reconnect to the new port that the server has given it. The same innitial connection sent by the client is sent to the server. At this point connection is established with the server. This arbitrartion is only necessary with a client that will be participating as a collaborator in the collage session. For a client that will just be sending data, this arbitration is not necessary. The collage clients may receive any DTM class. Any class that it doesn't understand, it ignores. The DTM classes collage currently understands is: DTM release: RIS8: for raster images SDS: scientific data sets (n dimensional array's of any type) PAL: 8 bit palettes MSG: sending messages (chat box) Collage specific: (several of these will be integrated into DTM 2.4) COL: selections & doodles (no longer sends as of 1.2 only recieves) DOL: selection & doodles (new to 1.2) SRV: for establishing/closing connections ANIM: animation commands TXT: sending text editing messages Each of these classes has the additional field of a userID of the sender set with XXXsetID("namehere"). When sending RIS8 and SDS, usually a palette is associated with the image. After the RIS8 or SDS has been sent, the palette is sent with an associated tag in the header. COLsetAssoc(header,"name of data associated") will let the receiver know that this pal should be used when displaying the image. The associated tag is also used when a data set and an image are related. This will cause selection in collage to appear on both the image and dataset. Animations are sent across as 2d SDS. The DTM header is marked "to be treated as an animation". This is done with the ANIMmarkAnimation(header) call. This will cause collage to put the SDS in an animation window rather than a single frame window. Additional frames with the same name and animation mark will be appended to the animation sequence in the order that they are received. The source distribution of collage comes with the DTM extensions, some of the DTM routines used to communicate will collage will be found in there. Additionally, if interested in seeing collage communication source, see the module net.c. This module is highly portable and has been added to several NCSA data analysis tools easily so as to allow them to communicate with collage.