3.4.1 Fireworks User Guide

Complete:

Running cmsShow

Fireworks event display can be run from a CMSSW environment or from a standalone tarball. In CMSSW just run cmsShow executable available from your path while in standalone mode you have to specify a full path, e.g: ./cmsShow. There is a collection of standard sample files available on the web: you can access it via the menu entry File->OpenRemoteFile .

Standalone tarball is distributed with two sample data files, data.root and mc.root, so you can do:

./cmsShow data.root

When application starts, the main window with the most important controls shows up. Below is a screen shot of top frame with names of individual GUI controls: these will be described in detail in further sections.

Configuration

Everything you see in Fireworks can be saved and restored from configuration file. Menu action File->Save Configuration or shourtcut Ctrl+s saves parameters into current configuration file. This file can be used later when running cmsShow with the --config-file option (-c works, too).

Fireworks has some predefined configuration files: default.fwc (used when no config file is specified), ispy.fwc (focus on calo rec-hits), and pflow.fwc (provided by the particle-flow group). To start an /empty/ display, without any collections loaded, use the --noconfig option (-n).

Since cmsShow36 it is possible to change configuration at run-time via the File->ReloadConfiguration menu entry or short-cut Ctrl+l .

Views

View Types

Fireworks has 13 different view types. A new view of any type can be created at runtime via View->New View menu entry. The view-types can be divided into graphics views (drawn using OpenGL) and table views:

• Graphics Views
  • 3D perspective views There are two subtypes 3D and iSpy view. They show same collections, with the following difference:
    • iSpy view show RecHits and Digis in their geographical position.
    • 3D view shows CMS.CaloTowers, split into ECAL and HCAL contribution.
  • Histogram views have three subtypes: Lego, HF, and PF ECAL Lego type. They show collections as a eta-phi histogram and have a special camera handling feature that allows flipping from orthographic top-view to 3D perspective view.
    • Lego view presents calo towers are show as stacked lego plots (HCal on top of ECal).
    • HF view is a specialised visualisation of HFRecHit collection.
    • PF ECAL Lego view displays EcalRecHits instead of CMS.CaloTowers and also displays particles reconstructed by the CMS.ParticleFlow algorithms.
  • Projected views use non-trivial Rho-Phi or Rho-Z projections (see more info in Projections FAQ). Currently there are three projected view types: Rho Z, Rho Phi and PF Rho Phi. They show the same collections with the exception of CMS.ParticleFlow view, which shows EcalRecHits at ECAL barrel radius and CMS.CaloTowers at HCAL barrel radius.

• Table Views
  • Summary view: serves as the main access for controlling event content to be displayed. It is located in the left side-bar and contains a list of all EDM collections registered for display. This list can be used to control collection visible (see Visible and invisible items), their color, and to select objects (see Selecting). In addition, there are short-cut icons on the right side giving access to Filter and Data tabs of the collection controller (see below). Further, when a collection is expanded, basic information about each collection entry is displayed: controls for visibility, color and selection of individual element are also available.
  • Table view contains detailed information about any EDM object (physics objects, triggers, ...). For each collection type, tables show an initial choice of variables (columns), the selection depending on the EDM type. Table contents can be changed by the user - the changes are saved and restored as part of the configuration.To sort the tables, click on the column headers.
  • Trigger views: two types are available, showing L1 and HLT info.

ViewerGL Camera Interactions

Viewer interactions with the camera are summarized below. In each case the interaction is listed, along with description and user actions required to achieve it.

• Note for orthographic cameras:
  There is no field of view of view/focal length ­ dollying and zooming producing an identical scaling action.
  There is a fixed eye direction ­ so the Orbit` action is disabled.

• Note for perspective cameras:
  Dollying (moving the camera backwards/forwards) and zooming are often confused, and may appear very similar.
  When you dolly the camera the lens focal length does not change, hence the distortions associated with the projections are unaffected. However the movement can result in objects coming through the front` of the camera and disappearing.
  When you zoom, the camera does not move ­ hence clipping of near objects is unaffected. However with extremely small zooms (FOV large/focal length short) noticeable distortions, causing straight lines to become curved, can be seen with objects near the camera ­ the fisheye` lens effect.
  Generally dollying is more `natural`, but you may need to use both to achieve the desired perspective and eye position ­ particularly when you are working inside or very close to 3D objects.

Window Management

The viewing area of the main window is divided vertically into two slices: the left one contains a single view while the right one packs all other views in a vertical layout.

Each view has a title-bar that also contains window control icons:

• You can swap view on the right side with main view on the left side with click on icon.

• Any views can be un-docked from the main Fireworks window by clicking icon. This is handy if you want to see the graphical views of the event and the detailed information in the tables side-by-side, for example, or if you want to show several views in large windows or on several screens.

View Controller

Views have several properties that can be modified by a user in GUI window, called View Controller. It is activated by the info icon on the title bar.

Properties of graphics views are grouped into categories and put into different tabs. Style and Scale tab are common to all graphical views. In the Style tab you can set parameters for screens shots, change line widths, change color palette, or add the event label and CMS logo. In the Scale tab you can choose to ignore global energy scale and set view-specific scale parameters (see section CommonPrefrences).

This widget also allows you to save the given view as an image. The image will have the same resolution as the window but it can be scaled up by the "Image scale" entry in the "Style" tab. Most GL implementations will allow you to go up to 8192x8192 pixels. When going beyond 4096 pixels image export might take a while and machine could appear to be frozen during that time.

EDM collections

Fireworks supports visualisation of almost all EDM collections, at least via the table view. Based on C++ type of a collection a suitable plugin is selected to transform it into visual objects shown in different views. A complete list of such plugins is available here: plugin list.

Add collection dialog

Collections are added from the Add Collection Dialog activated via a button on top of the Summary view.

Collection controller

Collections hold the default color and visibility properties for their elements (these can be set in the Collection Controller or directly in the Summary View). To open the Collection Controller window, click the info icon on the right of the collection's name in the Summary View or use the Window -> Show Collection Controller menu - currently selected collection will be shown.

Filtering collection elements

The Collection Controller can also filter and select items in a collection. For example, it can make all jets with Et < 15GeV invisible. See Filtering and Selecting below. To limit clutter in the views, it may be desirable to make low-energy objects invisible. Filtering is accomplished by entering a filter expression in the Collection Controller window (see Controlling collection properties above). This expression is interpreted using the standard CMS CMS.PhysicsTools parser. The parser can call any public const member function of the object and do simple mathematical expressions. The objects for which the filter expression is false become invisible in graphical views and are shaded in the table views. When any element in a collection does not pass the filter, the corresponding icon in summary view changes from to . A very important feature is the ability to explore the available methods: pressing Tab will list all the possibilities, making it easy to build a custom filter.

Inspecting objects

Using table views

When inspecting objects it is often helpful to see arbitrary values derived from member-data. Table view allows you to do that by adding new columns and specifying custom expression.

Object controller

Each object has two properties: color (including transparency) and visibility. The user can select a non-default color for an object, for example to identify a "special" electron in all views. Both properties are controlled by the Object Display Controller. This controller window opens from the Window -> Show Object Display Controller menu, by the command key   i, or via the context menu.

Context menu

Context menu pops-up when right mouse button is pressed over an object. The basic context-menu entries allow setting of object visibility and color, opening of detail-views, and opening of object and collection controller windows. Additional options are available in graphics views, depending on the view-type:

• adding an object annotation;
• set / reset center for camera rotation

Sometimes one also want to completely reset the camera parameters: this is done by pressing Home key on Linux and Fn+Left on Mac (the same key combination is used to request going to the top / first page in most Mac applications). For more information about camera handling see chapter Viewer Camera Interaction

Detail views

Detail views are accessible from the Object Controller and from the Context menu. Fireworks provides detail views for Tracks, Electrons, and CMS.CaloTowers.

Multiple selection

Multiple selection is requested by Control-clicking a set of objects. If the clicked object is already in the selection, it is removed. A set of objects from the same collection can be selected by typing an expression in the Select tab of the Collection controller.

Invariant Mass Dialog

Invariant mass of a set of objects can be obtained from the Invariant Mass Dialog (menu entry Window->ShowInvarantMassDialog ). Mass of all objects is assumed to be zero (masses obtained from reco::Candidate objects are often nonsensical).

Changing color of all selected objects

When multiple objects are selected, the Object controller allows you to set visual properties for all of them simultaneously.
Note: Currently, this does not work for ECal and HCal towers (limitation of low-level calo-tower implementation).

Event filtering

Event filtering window is activated by the button below Run/Lumi/Event entries (see control layout)

Event filtering is a powerful tool for selecting interesting events based on a complex selection anything that you can use as selection in a Draw command in FWLite/Root will work. You may also filter on HLT triggers. When event-filtering is enabled, all event navigation is restricted to events that passed the selection.

Each filter expression is interpreted by Root's TTree::Draw(), and only events for which the expression is true are displayed. For convenience, collections can also be referred to by their Fireworks names (the names displayed in the summary view) rather than their FWLite names which tend to be rather arcane.

Examples:

• $Electrons.pt() > 10 Select events where there is at least one electron in the Electrons collection ("gsfElectrons" by default) with pT at least 10GeV.
• $Jets[0].pt()>50 && $Jets[1].pt()>20 Request the leading jet in the Jets collection to have at least 50GeV and the second leading jet to have at least 20GeV.
  Note: Not all collections are sorted, for example, Muons are not!
• $Muons@.size() == 4 Request 4 muons.
• $L1-Muon.@obj.size()>0 Will require at least one L1 Muon in the event. One can obviously couple this with additional requirements on its Pt, for example.
• $HCal.obj.hadEnergy() > 3 add .obj in expression because CaloTower is a collection of collection. Tou may look the structure in TBrowser.

Common preferences

Common preferences are available through Window->CommonPreferences menu entry or with the Ctrl+a short-cut.

Global Energy Scale

In common preferences it is possible to control the global energy scale mode and parameters:

• Fixed mode: scale defined with [GeV] [m] conversion.
• Automatic mode: scale is different on each event, so that objects fill up the specified height.
• Combined mode: scaling is fixed as long it does not exceed given height, auto-scale is applied after that.

Colors settings

Second part of Common preferences dialog are color setting. It is possible to change background color, color contrast, and colors used for geometry outlines.

Advanced Topics

Advanced file input

• Fireworks allows to open individual files as well as group of files:

     ./cmsShow data-01*.root 

• Linux build of Fireworks supports remote access to Castor, dCache(FNAL and other tiers), http, and xrootd. For example:

    ./cmsShow dcap://cmsdca1.fnal.gov:24140/.../XY.root 
    ./cmsShow /castor/cern.ch/cms/store/ .../XY.root.
  

• Notify cmsShow via port. For example, command `echo /tmp/sample.root | nc localhost 9091` will load sample.root file, where cmsShow has been started with --port option. This option is very useful for live event displays where new files are loaded without human intervention. Frequently used with the --chain option, which allows you to specify how many files are kept in the file queue.

Making Images for Media

Fireworks configuration files for this purpose: fwc collection. All windows fit within 1280x1024 screen (if you are contributing config files to this collection, please do the same).

It is advisable to start from one of the configurations available above and to allow arbitrary color selection for event collections and items (click "Color wheel" button in color-selection dialog), e.g.:

cmsShow --free-palette --config-file media-1.fwc data-file-or-url.root

Advice

• Make windows sufficiently large before saving an image.
• Choose background color based on the context where images will be used ( Ctrl-b switches between black and white background). If in doubt, make both versions.
• Try enabling shape outline (use t and r keys to switch).
• Try enabling full scene antialiasing / multi-sampling for ROOT GL (this might not work for remote displays). Add this to your .rootrc:
  

  OpenGL.Framebuffer.Multisample: 4

Review status

Reviewer/Editor and Date (copy from screen)	Comments
AntonioMorelosPineda - 15 Feb 2013	Upgrade to workbook style
AljaMrakTadel - 08 Mar 2011	Created.

Responsible: AljaMrakTadel
Last reviewed by: AntonioMorelosPineda - 15 Feb 2013