To use this tool you will need two pieces - the off world piece can be obtained here ExcelSecondLife.zip

The inworld piece can be had for free at the prim plotter dispenser available at the Dataviz site at this SLurl

Data Visualization

University of Michigan Plotter Prim Tool

User Manual

 

Rev 1.01

April 2008

 Anne Ogborn Engineering

 

This work was funded by NIH grants RO1GM078200 and P20HG003890

to Gus R. Rosania. The plotter prim or any part of the script contained

therein can be copied, modified and distributed based on the creative

commons license as specified in

http://creativecommons.org/licenses/by-sa/3.0/. 

Any copy, modifiedversion, or derivative work of this plotter prim (including the script

or any part of it) should also include the following acknowledgement:

"The original plotter script was designed and produced by Gus R.

Rosania (Caia Alter, SL) and Anne Ogborn (Annie Obscure, SL), and

released on June 1, 2008."

 

 

Rev history

1.0    initial release

1.01  added legal boilerplate, changed name 

 

 

 

Overview

The Plotter Prim provides a rapid method of creating image data arrays and data scatterplots in Second Life™.

The system provides a rapid method of creating 2D and 3D image arrays and charts from data in Excel.

 

 

 

Displaying data starts with preparing a stock of imageprims to use. How to do this is described under Setup.

To display data, copy the data into an Excel spreadsheet based on the template provided with the delivery. Export the data to a notecard in second life. Drop the notecard into the Plotter Prim, and order the Plotter Prim to creates the image display.

Installation

System Components

Obtained in Second Life from the Prim Plotter dispenser at the DataViz site: Data Visualization

·        CAIA 3D Rezzer rev 1.0  (the plotter prim)

·        imageprim (contained in the rezzer) 0.9.2 direct

·        UUID tool 

·        sample notecards

·        builders grid

 

Obtained from this wiki page:

·        ExcelSecondLife.xlt

·        User Manual (this document)

·        Sample excel files

Install Procedure

Excel

Unzip the zip file in the off world delivery ExcelSecondLife.zip.  Copy everything into a safe location. Quit any running copies of Excel, and copy the ExcelSecondLife.xlt template to  C:\Documents and Settings\<user name>\Application Data\Microsoft\Templates. Start Excel and make a new spreadsheet. You should be offered ExcelSecondLife.xlt as one of the template options. Quit Excel.

Second Life

Make a backup copy of all items given you in SL. The objects given you have full permissions. This includes permission to mess them up.

If you have a usual place you will be using the tool, perform the procedure outlined under setup to make a stock of imageprims.

Work Area Setup

Before using the tool in a region, you will need to create a stock of imageprims.

 

 

 

The Grey Goo Fence

The reason for this procedure is that Linden Labs deliberately limits the rate at which prims can be rezzed by another object, a limit called the 'Grey Goo Fence' (it was originally installed to prevent a form of greifing called 'Grey Goo').

To avoid the Grey Goo Fence, we rez a stock of 'data point' prims, which we call imageprims, beforehand. When not in use, these imageprims are transparent and phantom, and thus not detectable during normal SL use[1].

imageprim bands

As part of the setup procedure, you will rez a stock of imageprims.

Each imageprim has a unique id number associated with it. Id numbers start at 0 and continue to 65535. All graphs and Plotter Prim users within a region must cooperate in dividing up 'bands' of id numbers for their use. It is not necessary (or even possible) to actually have an imageprim made for each id. You should avoid making multiple imageprims with the same id.

For example, a scientist user shares a region with one other scientist. They agree that the other scientist will have all numbers above 32000, our scientist from 0 to 31999.

Our user decides to make 4000 imageprims numbered 0 to 3999, and another 50 imageprims numbered 30000-30049 for a scale.

She places a rezzer on the ground, sets it's band to 4000 prims starting at 0 and issues the make command (how to do this is covered in the next section and in 'CAIA 3D Rezzer Use').  This process takes as much as several hours, but need be done only once.

She also makes 50 prims strting at 30000, and then displays a scale. Her work area is now set up.

She has 800 data points she wants to examine. She creates a notecard for the 800 points, sets the rezzer's band to 1000 points (to be safe) starting at 0, and displays the data.

She examines the data, changes how it's generated in the excel sheet, and copies it into the notecard, then displays the data again. Since she's using the same imageprim band, the old display is replaced by the new.

She sees something interesting in the data, and wants to create a second graph atop the first, maybe with a slightly different model. She sets the orientation of the prims to pi / 8 in each direction (so overlapping prims can be distinguished) and creates a new notecard.

She changes the band to 1000 points starting at 2000, and displays the new notecard. The new data is displayed atop the old.

When finished she sets the band to 3000 points starting at 0, and hides the data to clear her work area.

A maximum of15000 prims are allowed in a region by Second Life. This is independent of the numbering system, and of course a set of users in a region must also cooperate in respecting this limit.

Making imageprims

To make imageprims, set your Second Life logout time to a long value.

Rez a rezzer and position it clear of the ground as described in Plotter Prim Use.

Touch the rezzer to display a blue dialog in the upper right corner of your screen. One of the options will be 'set band'. Click this button.

Type the starting number and length of the band on channel 99. You can chat on a channel by starting your message wth a slash immediately followed by the number of the channel. So, to make your band 200 points starting at 500, type

/99 500 200

 

 

 

Touch the Plotter Prim again, and this time choose 'make'[2].

You will see something like this

 

 

 

Plotter Prim during making, with imageprim above

 

 

 

The Plotter Prim will display floating text showing how many imageprims it is making. 

When it finishes the imageprims will vanish. They're still there, they've just become invisible. Use ctrl-alt-T to make them appear a smokey red, ctrl-alt-T to go back to normal. This is a handy trick any time you want to find 'hidden' imageprims.

imageprims after making finishes – use ctrl alt T to get this

 

 

 

Should you decide you want to get rid of some imageprims, either use ctrl-alt-T to find them or create a notecard that 'displays' them in the center of the imaging area so you can see them. Select and delete them normally.

Do not make multiple imageprims in the same region with the same id. Should you accidentally do so, use one of the tricks in the previous paragraph to delete them (both copies will act together, so they'll be directly atop each other).

Use

Excel Spreadsheet preparation

The first step in actually using the system is to prepare the data. Wherever the data originates, you'll need to import it into an excel spreadsheet based on the ExcelSecondLife.xlt template.

You can present data to the system in two ways.

First, you can present data as a table of values. This would be used for a scatterplot , image scatterplot , or other sort of plot. In this mode you supply a normalized x,y,z position for the data.

Second, you can create a two dimensional grid of cells. For example, suppose you have a set of images you want laid out in a grid.

Array mode is handled by a tool that automatically creates scatter plot data, gridding the points. So array mode can be thought of as an extra step to scatter plot mode. 

Accordingly, we'll discuss scatter plot mode first.

Scatterplot mode

The 'data' worksheet of the ExcelSecondLife based workbook has columns for the data. Data will be read until the first line with a blank in the X value (column A), so you can't have interruptions in the data.

the columns

Columns X,Y,Z are required, the others may be blank.

 

 

 

X	The normalized X value. That is, a value of 0 will line up with the X axis and a value of 1.0 will be the distance specified as the size of the X axis away[3].
Y	The normalized Y value. That is, a value of 0 will line up with the Y axis and a value of 1.0 will be the distance specified as the size of the Y axis away.
Z	The normalized Z value. That is, a value of 0 will line up with the Z axis and a value of 1.0 will be the distance specified as the size of the Z axis away.
UUID	The Second Life UUID of an image. Obtaining the UUID is discussed below.
URL	A URL that will be loaded if the imageprim is touched[4].
Red	The normalized 0 to 1 red component of the imageprim color. All faces except the image face (if there is a UUID) will be set this color
Green	The normalized 0 to 1 green component of the imageprim color. All faces except the image face (if there is a UUID) will be set this color
Blue	The normalized 0 to 1 blue component of the imageprim color. All faces except the image face (if there is a UUID) will be set this color
Text	A text string that will be displays as floating text on the image.
Info	A string that is passed to another script inside the prim. See 'advanced tricks' for a full discussion.

 

 

 

Getting UUID's

Provided with the delivery is a tool for obtaining the UUID's of uploaded images.

Rez the UUID tool and copy the image textures into its contents (you'll have to drag to the contents tab, dragging to the object textures the object instead).

Touch the tool, and it will say the data. Copy and paste this from your Local Chat tab of your Communications window and paste into a notepad .txt file. Save and import into Excel, choosing commas as delimiters. You'll get 3 columns, one is trash, one is the UUID, one is the name of the texture.

Large and small data sets

The provided Excel template handles 4096 rows of data. If you need to handle more than that, you'll need to follow this procedure (which will somewhat slow down Excel):

1.                  Unprotect the 'data' worksheet

 

2.                  Select the last non blank line of column U and V and copy them down as far as needed.

3.                  Reprotect the worksheet.

 

Setting the meta data

Global information about how to display the data is on the Meta worksheet.

The area under 'Work Area format' is used with array mode and is described there.

Image prim default color is the color used when the color columns of the data are blank.

The image size is the size of the imageprim in it's local coordinates, in meters.

The array origin is not used. The origin is taken from the location of the rezzer prim. The array orientation is not used. The orientation is taken from the location of the rezzer prim. These two items are provided for future compatibility. They would be activated by the '1=use prim,0=use rezzer' data.

Array size is the size of the entire display space, in the local rezzer coordinate frame.

Image orientation is the Euler angle rotation SLERP rotation (Second Life Euler ) angle of the image with respect to the local axes of the rezzer.

 

 

Copying data to the clipboard

After the data is filled in it must be copied to a notecard.  Use the 'Copy Data' button at the top of the data worksheet. If you have manual recalc turned on, it may be necessary to unhide the 'compute' sheet and recalc it as well as the meta and data sheets before copying.

Sign on to Second Life, click the Copy Data button to put the data in the clipboard, and then create a notecard in your inventory. Name the card something short (it'll be the button name, max 8 chars). Paste your clipboard into the notecard.

The system isn't very forgiving of extra lines (a design tradeoff for speed), so be sure if you overwrite an old card you select every bit of it (ctrl-a) and paste.

Drop the card into the rezzer.

Alternatively you can open the contents pane of the rezzer and paste the data into an existing card..

 

 

Array mode

Image arrays can be made in a semi-automated fashion using the Work Area sheet and the Work area format of the Meta sheet.

Create a map of your image array with repeated row and column sets of multi-column data. For example, if you have a URL, UUID, and some other data (say a retention time) for 4 images that you want displayed in a 2 x 2 array, set up your Work Area like this:

 

 

 

URL1	UUID1	Retention1	URL2	UUID2	Retention2
URL3	UUID3	Retention3	URL4	UUID4	Retention4

 

 

 

 

The 'stride' of the data is the number of colums you must shift to see the same data for the next value. In this case the stride is 3.

On the Meta sheet, fill in the stride. For each column you want copied into the data sheet, put the (1 based) offset of that column in the appropriate box. For our example, we'd use URL=1, UUID=2. Set all other offsets to 0.

Click the Place Array button. It will ask you to confirm that you want to clear the data if you have data in the data sheet.

 

 

Plotter Prim Use

The Plotter Prim has several built in tools to help you align it.

 

 

 

 

 

 

The axes for the graph are aligned with the axis pointers on the Plotter Prim.

You can use the point of the cone to ensure that the Plotter Prim is lined up perfectly with an external object like a grid. Note that the center of the Plotter Prim (the point shown by the arrows in edit mode) is NOT at the intersection of the axes pointers. The 0,0,0 point of the graph is where the pointers meet, not at it's Second Life center.

The Grid Panel shows the plane image arrays created with Array Mode will be placed in.

Do not rename the imageprim or Plotter Prim. The names are used by the scripts.

Site the Plotter Prim

Rez the Plotter Prim, and then consider how high off the ground it needs to be and how it should be oriented. Data points below ground will not be placed properly.

Do not place the Plotter Prim near a region boundary. The Plotter Prim will not operate properly across a region boundary.

If you haven't made the imageprims, make them now as outlined above.

Create Notecard

Create the notecard as described in 'Copying data to the clipboard'. You can keep up to 8 cards in the Plotter Prim at once.

 

 

Set imageprim band

Select a band of imageprims.

Touch the Plotter Prim to display a blue dialog in the upper right corner of your screen. One of the options will be 'set band'. Click this button.

Type the starting number and length of the band on channel 99. You can chat on a channel by starting your message wth a slash immediately followed by the number of the channel. So, to make your band 200 points starting at 500, type

/99 500 200

 

 

 

display

Touch the Plotter Prim to display the dialog again. Click the name of the notecard.

 

 

hiding data

Touch the Plotter Prim to display the dialog. Click 'Hide'.

 

 

Advanced tricks

multiple plots in the same space

You can create multiple series from heterogenous data by repeated plotting over the same space. Simply change bands between plots.

 

 

replacing the imageprim

You can control the appearance of the resulting objects to a limited extent by altering the imageprim. For example, you might change the imageprim to a sphere for a scatterplot.

Multi-prim objects as imageprims have not been tested. They should work, and might be useful in some circumstances (eg. multiple bar charts). If you change the imageprim you'll need to delete any that were in that range and then remake them.

 

 

using the Info column

Data in the info column will be passed as a llMessageLinked message to LINK_SELF.

If you add a script to the imageprim (this counts as 'replacing the imageprim' above, see the cautions about remaking), you can control the prim in many ways.

Some possible applications:

Bubble plots

rotated variable length arrows for plots of vector field phenomenon  like magnetic fields, fluid flow, etc.

plots that animate with time.

plots that display network relation data by the 'particle chain' trick.

image plots of photographs showing the orientation and location of the camera at the time.

scales

You can use the Plotter Prim to make scales for it's own plots, simply by generating the scale 'ticks' as imageprims. One of the samples creates a simple scale.

 

 

 

Appendices

 

The Samples

Samples are from beta copies of the template and may not match the final template exactly.

 

 

 

imagearray.xls

demonstrates creating data in Array mode

 

 

 

scales.xls

demonstrates creating scales

 

 

 

respiration.xls

Using data from the manyeyes project, relates # of hospital admits, # of respiratory admits, and average temperature for one month in 5 cities.

 

 

 

the data format for the notecard

 

 

 

   Univ. of Michigan Plotter Prim Format

 

 

 

   Anne Ogborn, April 22, 2008

            Rev 0.9a

(no settext or color)

 

 

 

   A data card for the rezzer shall consist of

data in lines. For efficiency in execution no variation

in line formatting is permitted - e.g. blank lines are not allowed,

there is no comment facility, etc.

In particular, it is important that there not be blank lines at the bottom

of the list

 

 

 

   Data is in UTF-8, Lines are separated with 0x0D 0x0A (CRLF). Line length is limited by max allowable width of the constituent fields.

 

 

 

   Data items are separated by ASCII ampersand character.

 

 

 

   The first line (called the header) contains metadata. The

remaining lines each define one image prim.

 

 

 

metaformat -

integer means an integer formatted as LSL's (integer) cast on string acceptor.

 

 

 

float means a floating point number formatted as LSL's (float) cast on string acceptor.

 

 

 

vector means a vector formatted as LSL's (vector) cast on string acceptor, that is, of the form <x,y,z>  where x,y, and z are floats and the angle

brackets and commas are included. Spaces are NOT allowed in format.

 

 

 

UUID means a uuid in standard LSL form, something like

3ce91aea-22d5-3cbe-5ea9-a9be8387e4ac

 

 

 

url_encoded_string means a string of up to 255 characters encoded as per

RFC 3986

 

 

 

Because of a bug in the LSL library that does parsing, zero length strings

are improperly handled. As a workaround, any text of zero length is substitued with a field consisting only of an asterisk.

 

 

 

===============header line format

 

 

 

id         integer              a unique key identifying this card, a 16 bit number represented in signed decimal

 

 

 

prim     integer              1 means use the origin and orientation data from

                                    this line, 10 means use the origin and orientation

                                    of the rezzer

 

 

 

origin    vector               the region coordinates location

                                    of the origin of the display

 

 

 

orientation        vector   the Euler angle orientation of the

                                    display with respect to the world coords

 

 

 

array_size         vector   the size in meters, <width, height, depth> of the                                                 display

 

 

 

image_size        vector   the size in meters of the image prims, <width, height, thickness>. This is in the image prim's coordinates, so thickness

is always how 'thick' the board is irrespective of rotation.

 

 

 

orientation        vector   the Euler angle orientation of the images with respect to the overall array orientation. <0,0,0> makes the image face the

positive Z axis and lie in the plane of the XY axis, bottom parallel to the X axis, up +Y axis.

 

 

 

===========data line format

 

 

 

location            vector   Prim center location in a normalized 0-1 space.

                                    So an image at <0,0,0> is at the origin, at <1,0,0>

                                    is at the outer end of the X scale.

 

 

 

UUID               UUID   UUID of the image to be used as a texture on the 0                               face of the prim. If

 

 

 

url                    url_encoded_string url to be loaded when the prim is touched

 

 

 

red                   float      0 to 1 red component of color. If the UUID is set then face 0 (the face with the image) will remain white. Otherwise all faces

are set to this color.

 

 

 

green                float      0 to 1 green component of color. If the UUID is set then face 0 (the face with the image) will remain white. Otherwise all faces

are set to this color.

 

 

 

blue                  float      0 to 1 blue component of color. If the UUID is set then face 0 (the face with the image) will remain white. Otherwise all faces

are set to this color.

 

 

 

text                   url_encoded_string String to be displayed as black floating text above the image.

 

 

 

info                   url_encoded_string String that will be transmitted as a link message with num = 77. This allows the user to add a script to the prim and pass added info to it.