Overview

The Citris Digital Gallery Builder is a collaborative virtual gallery system for the humanities.

The main idea is that it allows users to easily build 3-dimensional virtual galleries which contain various types of media, and which can then be viewed and modified collaboratively by several people at once over the internet. The gallery is designed, viewed, and modified entirely in 3D.

More overview is available here.

Currently supported media are:

images

jpeg, bmp, png

movies

mpeg

audio

3D Objects (meshes)

VRML2

images

movies

audio

3d media

The Citris Gallery Builder is written in Croquet, an open source collaborative and 3D environment built on top of Squeak Smalltalk. Croquet is still in beta, but a full 1.0 release is expected by the end of 2005.

System Requirements

The Gallery Builder has pretty much the same system requirements as Croquet, which are essentially: A contemporary, moderately fast computer with a contemporary graphics card and up-to-date drivers.
Windows, Mac OSX, and Linux are supported. (But Windows is supported most).
You will want a graphics card with as much texture memory as possible.
The more texture memory you have, the better the Gallery's performance will be with many textures.

From the Croquet website:

Download and Installation

All downloads are available on the download page.

Step 1 - Windows:

Download the most recent .exe full installer.
This is a regular windows installer, and will install the software to C:\ITHProject\CitrisGallery.
Icons to launch the gallery will be installed on the desktop and in the start menu.
The software can be uninstalled via the standard windows method of using Add/Remove programs in the Control Panel.

Step 1 - Macintosh and Linux:

Download and install Croquet itself from the Croquet Website.

Make sure that Croquet runs on your computer and that you basically understand how to launch .image files.

Only then, download the most recent .zip full release from the Citris Download Page, and unzip it into the Croquet folder.
The Citris .image file should be a sibling of the Croquet0.x.image file.

Step 2 - All Platforms:

launch the Gallery

Download the most recent .zip "partial" release.
These releases contain only the Squeak .image & .changes files which update the application.
They do not contain any sample data or other support files.

Unzip the file into the Croquet directory.
The new .image and .changes file should be siblings of the previous .image and .changes files.

Starting the Program

Windows:

To launch one of the pre-made Galleries which come in the installer, including a blank gallery,
you'll find them in Start | Programs | CITRIS Digital Gallery. The installer also adds shortcuts to the desktop.

To launch an updated version of the software, or to launch a gallery which you have saved as a .image file, browse to C:\ITHProject\JasmineGallery, locate the .image file you wish to run and the "Squeak" shortcut file, and drag the .image file on to the Squeak file. - This is the standard way of launching projects in Squeak.
(You may also be able to set up C:\ITHProject\JasmineGallery\bin\Squeak.exe as the default application for launching .image files, which would enable you to just double-click the .image file. In practise, i find it convenient to add Squeak.exe to my "send to" menu, which then allows one to right-click a .image file and send it to Squeak.)

Step 1 - Macintosh and Linux:

Locate the .image file you wish to run and launch it in the usual Squeak fashion.

The program should start up looking like this:

The gallery right after startup

Navigating in 3D

In the 3D window, it's easiest to navigate with the keyboard.

Note the keys in the heads-up display which show which keys you are currently pressing.
You can also press these buttons with the mouse to navigate.
(Macintosh note - you need to engage Caps Lock for keyboard navigation)

When using the top-down view, the effect of the keys changes to this:

You can also navigate by holding down the right mouse button and moving the mouse to different regions of the 3D window.
(In Squeak lingo, the right mouse button in Windows is "Yellow", and the left mouse button is "Red".
Results may vary with other operating systems. Sometimes the yellow mouse button is the middle button instead, sometimes the left.)

Go Forward & Turn Left	Go Forward	Go Forward & Turn Right
Turn Left		Turn Right
Go Back & Turn Left	Go Backward	Go Backward and Turn Right

Feature Tour

This section will walk you through one of the pre-built galleries which come with the installation.

Feature Tour Contents:

Start the "example gallery lite" image.

Initial scene elements

Navigate forward

3D Native American Basket, scanned in and loaded as VRML.

Manipulate the Basket

Move the mouse cursor over the basket. Notice that the cursor changes to a pointing hand, and the basket stops rotating.
Tap the space bar. A transparent box will appear around the basket. This is called an "EditBox", and is used to move, rotate, and resize 3D objects.
Tapping space is a common method of manipulating objects in the Gallery. For example, 3D Objects, Walls, Wall Objects, Annotation Markers, Lights, etc, can all be manipulated with space.
By click-and-dragging on the EditBox, you manipulate the basket. The faces of the box are used to move (translate) the box, the edges are for rotation, and the corners for resizing.
Move the mouse cursor over and edge of the EditBox. Notice the cursor changes into a Rotate glyph.
Click-and-Drag the mouse to rotate the basket.
Try the different edges, try the faces, and finally the corners.

EditBox used to manipulate 3D objects.

When you are done manipulating the basket, mouse over the edit box and press space again.

Play a Movie

Press the E key to turn right until the wall with the big black rectangle is in view.

Movie Player and Controls.
(Movies currently appear black until they are first played. This will hopefully be fixed.

Click the "Play" button, and the movie plays:

Movie Player doing its thing.
Note the "% Played" control has advanced.

Manipulate the Movie

Mouse-over the movie, and, like the basket, press the space bar.
Three "Draggers" appear on the movie: two at opposite corners, and one in the center. The draggers in the corners resize the item, and the one in the center moves it.

Wall Item draggers.

Click-and-drag on the lower-right dragger to resize the Wall Item:

Resized Wall Item.

Wall Item Options

Nearly all objects in the gallery have an individual item which can be opened by clicking on them:

Context-Sensitive pop up menu for a Wall Item.
Note that the menu title shows what kind of object the menu referrs to.

In the Options submenu, uncheck the Lock Aspect option, and then resize the movie again:

Wall Item resized with free aspect ratio.

Clamp to Wall limits the Wall Item to be on the wall. Without it, Wall Items can be moved outside the border of the wall.

Shading controls whether shading effects operate on the item. This can be useful in otherwise low-lighting.

Restore the Movie's Original Aspect Ratio

Tools

choose Original Aspect. You may need to do this after stretching a wall, or copying-and-pasting content from one wall to another. (Or, of course, if you've stretched the item as above)

You should probably make the movie large again by opening its menu and re-checking Options | Lock Aspect, and then use the draggers to make it large again.

Annotate the Movie.

Add an Annotation Marker by bringing up the movie's menu and selecting Insert | Marker.
This will create an Annotation Marker attached to the mouse cursor.
Annotation Markers are cones which draw attention to the exact spot of interest.

Move the marker where you would like it, and then press the mouse button once.

An Annotation Marker dropped on a Wall Item.

To reposition the Annotation Marker, you guessed it, mouse-over the marker and press the spacebar.

To change the annotation text, from the Marker, choose Modify | Annotate.
This opens the annotation dialogue:

Annotation Dialogue.
This is currently the mechanism for viewing an annotation, as well as writing one. In the future, viewing the annotation should be simpler.

Add a Wall.

Press E to rotate further right, until you see the open space in the gallery:

Open space!

From the Main Menu, select Insert | Wall:

Main Menu

Which creates a new wall in front of you:

Presto! A new wall.

Manipulate a Wall.

You guessed it again, press space over the wall to reveal the manipulation tools:

Wall Draggers.

Texture a Wall.

In the wall's menu, choose Modify | Browse for Texture to open the Texture Browsing Dialogue.

Texture Browsing Dialogue.

In the browser, double-click you way into Example Content/images/walls.

Choose any texture in the folder.

You can also browse to any .jpg, .png or .gif file on your system.
It's advisable to use images around 256x256 pixels or so.

New texture on a wall.

Note that recently-loaded textures are stored for your convenience in the Recent Textures menu:

Recent Textures convenience menu.

Layout Conveniences.

A convenient way to lay-out the walls of a gallery is with Blueprint Mode.
In the main menu, choose View | Blueprint Mode.

Blueprint Mode.

Other conveniences in the main menu are shown below:
View | Main View | Dual View, and
View | Draggers | Show All Draggers

Dual-View, All Draggers Shown, Blueprint mode On.

Add an Item to a Wall.

In the wall's menu, choose Insert | 2D Content to open the Load Content dialogue.
In the screenshot below, we've browsed to the folder "Example Content/images/

Load Content Dialogue.

Select an image and click OK.
It's advisable to use images of either 256x256 pixels or 512x512.
(Like all modern 3D graphics systems, all textures are internally resized up to the nearest power of two in each dimension. This means that if your image is 257 pixels wide, it will be internally resized to 512 pixels wide. This means that you'll save texture memory if you yourself choose the power of two beforehand which you want the images to be.

New wall item.

Add a 3D Model to the Gallery.

Navigate so that you have some open space in front of you; like walls, 3D objects are placed a little ways in front of you.
In the main menu, choose Insert | 3D Content.
This opens the "Load Freestander" Dialogue. (Freestander is another Gallery-term for 3D Model).

Load 3D Model Dialogue.
3D Model File Format Constraints:
- Only VRML (.wrl) files are supported.
- The files must be text.
- The files cannot contain actual texture data, instead they must refer to an external texture file.
- External texture files must be siblings of the .wrl file itself.
- External texture files must be referenced as filename only. eg: ImageTexture { url "1-71007-small.wrl.jpg" }

The object will be inserted into the gallery a little ways in front of you. It will be in an EditBox:

Freshly-added 3D Model.

More 3D Model Manipulating.

above

Tools | Sit On Floor - Positions the object so it's approximately sitting on the floor.

Tools | Align - Aligns the object with various world axes.

Tools | Spin - Makes the object spin at various speeds and along various axes.

Tools | Flip - Flips the object vertically.

Add a Light.

Navigate so that you have some open space in front of you, then
In the main menu, choose Insert | Light.
This adds a new point-light to the scene, a bit in front of you:

Freshly-added Point Light.
(Other lights are also lighting the scene)

For demonstration purposes,
from the light's menu, select Edit | Delete All Others.
This will delete all other lights in the scene, allowing you to see the lighting effect of one light clearly:

The same light, but with all other lights deleted.

Changing a Light.

From the Light's menu, choose Colors...
This brings up the color dialogue, which lets you change the colors and intensities of the light's various components:

Changing a light's colors.
(Other lights are also lighting the scene)

Click OK when you're done changing the colors.

From the light's menu, choose Modify | Type (t) | Spotlight.
This changes the light into a spotlight, instead of a pointlight.
Then, from the light's menu, choose Modify | Align | -Y.
This aligns the spotlight so that it's pointing down towards the floor:

Light has been transformed into a spotlight.

Position the mouse over the light and press the spacebar to bring up the light's EditBox.

Click-and-drag the lower edge of the EditBox to rotate the light away from you:

Spotlight pointing away.

Saving and Loading.

This is slightly different.
Find some empty space on the Squeak Desktop (not in the gallery) and click the left (aka "Red") mouse button.
This brings up Squeak's "world menu". From the world menu, choose save as new version:

Squeak's save menu.

This will create a new .image and .changes file pair.
These two files should be thought of as one file!
They are meaningless without each other!

To re-launch your saved version, see "Starting the Program", above.

The End.

This concludes the feature tour. These are most of the actions you perform while working with a gallery.
Following is a reference section, which documents all the various menu and key commands.

Reference

This sections lists and explains all the various keyboard and menu commands and features in the Gallery system.

Reference Contents:

Keyboard Commands and Shortcuts
Menus

Keyboard Commands and Shortcuts

Key	Function	Context

Navigation Keys The state and functionality of these keys are mirrored in the heads-up navigation keys buttons, which can be clicked with the mouse.
Q	Rotate avatar widdershins.	Empty Space, Single View Mode
Q	Move Avatar Forward and Left	Empty Space, Dual View Mode
W	Move avatar forward.	Empty Space, Any View Mode
E	Rotate avatar anti-widdershins.	Empty Space, Single View Mode
E	Move Avatar Forward and Right	Empty Space, Dual View Mode
A	Move avatar left. (Strafe left)	Empty Space, Any View Mode
W	Move avatar backwards.	Empty Space, Any View Mode
D	Move avatar right. (Strafe right)	Empty Space, Any View Mode
X	Move Avatar Backward and Left	Empty Space, Dual View Mode
E	Move Avatar Backward	Empty Space, Dual View Mode
C	Move Avatar Backward and Right	Empty Space, Dual View Mode
â†‘	Move Avatar Up (Vertically)	Empty Space, Any View Mode
â†“	Move Avatar Down (Anti-Vertically)	Empty Space, Any View Mode

Alt-A	Selects distance from camera to avatar.	Empty Space
Ctrl-R	Toggles a rear-view mirror.	Empty Space

Shift	When manipulating a Dragger or EditBox, changes the direction or style of motion.	Draggers, Edit-Boxes

Space	Toggles Manipulate Mode for Walls, Wall Items, 3D Models, Lights, Primitives, etc. The space bar is your friend!	Any movable gallery element.
T	Changes the style of a light between Point, Directional, and Spot.	Lights

CITRIS Collaborative Gallery Builder

Citris Collaborative Gallery Builder: User Guide

Table of Contents