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.
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.
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.
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.
See images of the same event in several different projections.
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.
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.
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.
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.
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.
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.
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.