Tscan

Tscan ("Trivial Scanner") is an event display, traditionally called a scanner, which I developed. It is a program that shows events graphically on the computer screen.

It was designed to be simple ("trivial") internally, and to have a simple user interface. A lot of importance was given to giving the user a large choice of options to display events in many different ways.

Tscan proved to be a very useful tool for the development of fitters. A particularly useful feature is the ability to show custom data for every photpmultiplier tube (PMT). Instead of the usual time and charge, it can show expected charge, scattered light, likelihood, chi-squared difference, patches, and any other data that can be prepared in a text format.

1 Features

A detailed description of features, command line options, and keystrokes is contained in the manual page. Some of the features are highlighted below.

1.1 Image Features

The flexibility of many ways to display an image was a major design goal.

The three-dimensional detector is shown in several ways projected onto a two-dimensional display. One way, is the standard unrolled cylinder image with side wall shown as a rectangle, and top and bottom walls shown as circles above and below the rectangle. There are several ways of showing a spherical image, as seen by an observer, onto a plane. Finally, there is a realistic perspective view and a stereo view. The view can be switched to the outer detector.

PMTs can be displayed in several ways: as a points, as a circles of fixed size, as circles with size adjusted depending on distance from observer, and, most realistically, as flat squares in three-dimensional space. They can be drawn as an outline, or as a filled shape.

Usually PMTs with small amount of charge are drawn small, and "hot" PMTs are drawn larger, but size can depend on other quantities as well. The function of translation of charge to linear size can be linear, square root (linear area), or logarithmic (for large dynamic range).

To enhance the perception of location within the detector and the sense of detector shape, all non-hit PMTs can be shown in gray, or detector shape can be outlined with a help of grid pattern (with adjustable grid density) (examples). Additionally two kinds of grid can be drawn centered on the observer point, which helps one to understand the projection of a spherical view onto the plane.

PMT colors can represent charge, time or two kinds of time of flight subtracted (residual) time. One kind of residual time assumes that all light arrives from the vertex (point residuals) the other kind assumes that light arrives at the Cherenkov angle from a linear track (long residuals). A histogram of the quantity used for color scale is displayed, with hits weighted by amount of charge (except in charge histogram). To improve print output in some cases, the image can be drawn in reverse video, i.e., with light background and dark lines. In addition, color scale can be replaced with gray scale to improve black and white printouts. The image can be saved to a file for printing.

Tracks contained in the data file (for example, reconstructed tracks, or Monte Carlo tracks) are shown primarily as continuous lines drawn where Cherenkov cone intersects cylindrical walls. Additionally, the projected entry and exit points are marked (extending the track forward and back) and perpendicular projections of the vertex to the nearest top, bottom and side walls are shown.

With single keystrokes the user can move within the detector, rotate the view, and also shift, stretch, and compress the color scale.

1.2 Other Features

The data can be read in three formats: old offsite zform format, current ZBS format, and in text format based on superform format. See example of plain text superform format for a pi-0 event. In the first two formats, the user can move in both directions, forward and back.

Details of the event information, including tracks and Monte Carlo information, can be displayed.

The exact state of the scanner can be saved to a file, so that later user can resume event viewing in exactly same state.

2 Under the Hood

Tscan is written in the C language. Graphical features are implemented using raw Xlib (a very basic, low level library for X-Windows) without any toolkit on top of it. This allows flexibility and avoids toolkit limitations.

The main loop consists of waiting for X-Windows events (key presses, window resizing, etc.) and reacting to them. The central routine is draw_detector, which draws all the elements of the image (except the color scale and histogram), using current projection and other settings.

In order to be independent of the input data format, all PMT hit information is stored in a custom structure. It is easy to add more data formats by adding custom read routines in read_format.c files. Internally, the detector geometry is stored in the old offsite skgeom structure, even when it is read from current format.

Most program settings are stored in user options structure uopt. These settings are written out to a file when saving program status. The file is just a shell script containing the tscan command with many options, one option for each setting. See example saved state script.

A data type enum was implemented to store a setting which can take several string values. Functions are provided for setting, reading, testing, incrementing and decrementing (modulo number of possible settings) of the enum type.

Amount of debug text output is adjustable with tdebug variable.

By default (except in perspective view), the initial view position is selected at the first vertex. In such a case, the initial view direction is based on the charge distribution around the vertex. The charge inertia tensor, where charge is projected onto a sphere and is treated like mass, is diagonalized. Its eigenvectors are used as principal axes of the view in such way that the viewer is facing the maximum charge direction, maximum charge spread is in the horizontal direction, and the distribution of charge in the vertical direction is smallest.

In the perspective view, the initial position is selected in a corner of the detector farthest from the majority of the charge, and view direction is toward the center, at angle of 45 degrees with respect to horizontal plane.

2.1 Projections

When writing tscan, a major objective was to support many different projections and to make it easy to add new projections as needed. A projection is a way of showing points in three dimensional space on a two dimensional screen. Drawing of any three dimensional object can be easily implemented, for example, if needed, drawing of the LINAC pipe, calibration sources, or the water pipes could be added. Examples of objects already implemented are Cherenkov cones (or, more precisely, their intersection with detector walls) and lines outlining shape of the detector when drawing detector grid. All those lines are curved lines (series of straight line segments) in three dimensional space.

See images of the same event in several different projections.

2.1.1 Steps

A projection is implemented as a two-step process. First, the most important step, is the translation of the three dimensional coordinates into a convenient set of two dimensional coordinates, which is independent of window size. The names of functions which perform this transformation start with r2f (real-to-flat). The second step is the transformation of those convenient two dimensional coordinates into window coordinates. The names of functions which perform this transformation start with f2w (flat-to-window). In most cases the two steps are combined by "wrapper" functions which perform the full transformation. Names of these functions start with r2w (real-to-window).

Each set of real-to-flat functions resides in its own r2f file. All data and functions in the file are private (static in C language terminology) except a structure which provides pointers to three interface functions. Adding a new projection involves, essentially, not much more than adding a new r2f file with the three functions. One of the functions is init_real_to_flat(), which informs the external code about the scale of the flat coordinates used, and initializes some internal data. Another is draw_outlines() which calls functions which draw objects in flat coordinates (circles, rectangles, curves, etc.). This draws an outline of the projection. No three dimensional point ever gets projected outside of the outline in the flat space. The final, most important, function is real_to_flat(), which performs the actual projection transformation.

Before performing the projection, the detector is rotated, to account for the orientation of the observer. In an unrolled view a simplified rotation is performed, limited to rotation around the z axis only.

Some of the projections are equal area projections. This means that an area of a sphere of a given size is always shown as an area on the projected image of the some fixed size, regardless of the direction where the area is located.

2.1.2 Unrolled Projection

In the unrolled projection, the side wall appears as a rectangle, which comes from cutting and unrolling the detector cylindrical side wall, and top and bottom walls appear as circles at the top and bottom of the rectangle. This view differs from the other views in that it does not depend on the location of the observer. The view is always relative to the detector center.

The patches used for a fast scattered light calculation. Each patch is assigned a random color. Central PMT of each patch is enlarged. This figure was made with tscan, using a generated synthetic event in text format with PMT time determined by the patch to which it belongs (each patch having a random time), and charge of central PMTs larger than remaining PMTs.

First, a decision is made as to whether the point belongs to top, side, or bottom wall, based on the angle of the point location measured from detector center with respect to the x axis. For increased speed, this information can be passed from the calling routine, in which case this step is skipped.

A position on the side wall is determined by its phi and z coordinates. A position on the top or the bottom walls is determined by its x and y coordinates.

The unrolled view is useful for seeing how and where the hit pattern is distributed within the detector.

2.1.3 Cylindrical Projection

In cylindrical projection, the viewer is assumed to be at the origin of a spherical coordinate system, facing direction phi=0 with the equator being horizontal. The coordinate phi determines horizontal position, while coordinate theta determines vertical position on the displayed image. The viewing area is a rectangle with coordinates in flat system ranging from -pi to pi horizontally and from -pi/2 to pi/2 vertically. Distortion is small near the equator (middle horizontal region of the viewing area), and large near the poles (top and bottom of the viewing area). In the grids below, lines are drawn every 10 degrees.

In a second version of this projection, vertical position is determined by sin(theta) instead of theta. Vertical viewing area is smaller, it ranges from -1 to 1. This is an equal area projection. However, distortion of shapes near the poles is greater than in the first projection.

The cylindrical projection is good for viewing planar events, for example two ring events or three ring events with small total momentum, as would be expected in many nucleon decay events. See an image of a two ring event in cylindrical projection.

2.1.4 Spherical Projection

In spherical projection, the viewer is assumed to be in a spherical coordinate system, facing the direction of the pole theta=0 (non-standard theta definition, ranging from 0 to pi instead of the usual -pi/2 to pi/2). Spherical coordinates are translated into polar coordinates with spherical theta being polar r and spherical phi being polar phi. The viewing area is a circle with radius of pi in the flat coordinate system. The least distorted area is at the center of the image (front pole), and largest near the edge (back pole). Note, that the figure shows grid with poles on top and bottom, not in front and behind the viewer.

In equal area variant of this projection polar r is sine integral of theta. The viewing area circle radius is sine integral of pi, approximately 1.85194.

2.1.5 Hemispherical Projection

Hemispherical projection is similar to the spherical projection. The difference is that the image is split into two hemispheres. In the forward hemisphere (shown as circle of radius pi/2) theta between 0 and pi/2 is shown. A second circle of same radius is drawn on the left side, showing theta between pi and pi/2 with pi (backward pole) being shown at the center of the circle and pi/2 (equator) being shown the the edge of the circle. Note, that the figure shows grid with poles on top and bottom, not in front and behind the viewer, just like in case of spherical projection.

This projection avoids large distortion near the back pole, but the price paid is having an image in two discontinuous pieces. The largest distortion is at the edges of the viewing areas, while the centers of the viewing areas are the least distorted. It is good for viewing back-to-back events as would be expected for many nucleon decay events. This projection is also available in equal area version.

2.1.6 Globe Projections

This projection is used frequently to map the surface of the Earth, and for sky maps. Like in the cylindrical projection, the viewer is placed in a spherical coordinate system with poles above and below him. There are two variants of the projection, both of which are equal area projections.

Sinusoidal projection is the simpler one of the two. The vertical position of a point is simply the theta coordinate, and ranges from -pi/2 to pi/2. Angle phi, which ranges from pi to pi, determines horizontal position. In order to achieve equal area projection, before plotting, the horizontal coordinate is multiplied by cos(theta). The width of the viewing area changes with angle theta. This gives the viewing area a characteristic rounded shape, elongated horizontally, with pointed top and bottom, where the poles reside.
Sinusoidal projection grid

The Mollweide projection is more complex. The horizontal coordinate is x=phi*cos(theta_M), the vertical coordinate is y=M*sin(theta_M), where theta_M is given by 2*theta_M+sin(theta_M)=pi*sin(theta), and M is a constant. theta_M is calculated iteratively using Newton's method. In this projection, the viewing area has an oval shape without sharp corners. Mollweide projection grid

See an image of a single ring event in Mollweide projection.

In the above two projections distortions are small at the center and close to the equator and are largest at the edges, particularly near the poles.

2.1.7 Perspective Projection

Technically, this projection is somewhat similar to the (hemi)spherical projection. The observer is assumed to be located in a spherical coordinate system, facing the pole theta=0 (not a standard theta convention). The spherical coordinates are translated into polar coordinates with polar phi being spherical phi and polar r being spherical tan(theta). In this projection r is naturally unbound because tan(theta) diverges for angles approaching 90 degrees. An arbitrary viewing area boundary is imposed. It is a square shape which encloses an area of x and y less than r_max=tan(theta_open/2), where theta_open is the opening angle of the view.

A small opening angle gives a zoomed view, as through a telescopic lens, similar to an isometric projection. Large theta_open gives a fish-eye lens view, which can be quite distorted in extreme cases when theta_open approaches 180 degrees. The default opening angle is 100 degrees, chosen to be a little over 90 degrees, in order to be able to see both walls when standing at a corner of the detector.

In this projection straight lines in 3D space remain straight on the screen. This property is very useful in making images very clear when seeing straight rows of PMTs or grid lines outlining the detector. This projection is very easy to understand by people who see it for the first time. Other projections can take some time to get used to. A drawback of this projection is that it does not show a full 4*pi solid angle view around the viewer.

See an image of a single ring event in perspective projection.

2.1.8 Stereo Projection

This view is simply a pair of perspective views as seen slightly from the left and from the right of the observer The distance between the views (between the "eyes") is adjustable.

The view from the right side of the observer is presented on the left side of the screen and the view from the left side, on the right. To see the stereo effect, user has to look at the right image with the left eye and the left image with the right eye, in effect crossing the eyes as if looking at an object nearby (somewhere between the screen and the eyes), but keeping the eyes focused at the distance of the screen. For most people it takes some practice.

By using a negative distance between the views parameter, the views can be reversed. In such case one views the right image with the right eye and the left image with the left eye. The images on the screen then cannot be too large, and the distance between image centers should not be larger than real distance between the eyes, otherwise the eyes of the observer would have to diverge, which is difficult to do. Observer should imagine looking at an object far away behind the screen but at the same time focusing the eyes at the distance of the screen. This viewing technique is easier to master for some people.

Alternatively the images can be printed and prepared for an easier view, which, however, requires special stereo viewing equipment.

See an image of a two ring event in stereo projection.

2.1.9 Line Discontinuity

When continuous lines in 3D (for example, Cherenkov cones and grids outlining the detector) are projected, discontinuities can occur. For example, in the unrolled view, lines cross from side wall to top or bottom, or in a hemispherical view, lines can cross hemispheres. This condition is easily detected, because real-to-flat functions return wall parameter which is different for each such area and line connecting two points in different areas is not drawn. It is more difficult to detect a discontinuity when a line crosses from one side of the same area to the other side, for example, in the cylindrical projection when it wraps around from left to right or from top to bottom.

A general procedure was developed to detect this condition. As an input, it takes the positions of two points in real space and in screen coordinates. It calculates position in the middle between the two real points and projects it to screen coordinates. Distances between the middle and the end points are calculated in real and window coordinates. Two ratios of the window coordinates divided by the real coordinates are computed. The larger of the two ratios is divided by the smaller one to produce a double ratio. Most of the time this double ratio should be close to one. When the result is greater than 10 it is assumed that the line is discontinuous and the line connecting the two points is not drawn. To save computing time, when the distance between two window pixels is small (less than 4), the continuity test is skipped and the connecting line is drawn.

2.2 Color

There are two ways to calculate colors in the color scale: HVC and HSV.

2.2.1 HVC

The HVC scale uses the X-windows Color Management System (CMS) to map colors to Tektronics Hue, Value, and Chroma coordinates. This color scale has a complex translation to RGB (Red Green Blue) coordinates. The distance between two points in the HVC coordinate system should be proportional to the percepted difference between colors. Tscan uses maximum Hue and Value settings for any given Chroma. Since colors in the color scale constructed in this way did not appear uniformly distributed (for example, green region was very small), attempts were made to equalize the scale and to selectively stretch some regions. But this equalization effort was abandoned and a simpler HSV scale was used, which gave much better results.

2.2.2 HSV

The Hue Saturation Value color coordinates translate to RGB values in a simple linear way. A small problem on LCD screens is that red, yellow, green, cyan, blue, magenta colors take a large part of the color scale while colors between them take a smaller part. In other words the red, green and blue components tend to turn on and off almost completely with too little middle values. This was adjusted by a power law formula. In reverse video mode (light background), some colors, especially around yellow, were too bright with too little contrast with background. To fix this, weights were assigned to color components (blue: 0.8, red: 1.2, green 1.6) and the value (brightness) was truncated if the sum exceeded 1.9.

Back to tscan


Tomasz Barszczak