Note: CassettePlayer has undergone a sizeable upgrade.

CassettePlayer

CassettePlayer is a tool designed to help in the assembly of the cassettes for the CMS HGCAL upgrade.

Whats in this Repository

Right now this repository contains everything related to cassette player. This includes:

• The main CassettePlayer App
• Tools to create configuration files for a demo cassette
• Presentations and data related to this project.

Getting up and running

CassettePlayer is primarily a gui app, build using the wxWidgets framework. wxWidgets is crossplatform and this application should compile on Mac, Linux, and Windows.

Warning: This app is in development, there will be bugs.

Requirements

Compiler and Build Tools

You must use a c++17 compatible compiler, and a CMake version greater than 3.14.

External:

The only dependency you need to manage yourself is wxWidgets. It can be installed from the website, or using a package manager. Due to its size, it is not downloaded automatically.

Automatically Downloaded

These requirements will be downloaded automatically by CMake. Unless you are doing development you should not need to think about these.

Logging

• spdlog, used for logging
• fmt, for string formatting

Serialization

• cereal, for serialization

Scripting

• sol2, scripting integration

Rendering and Vector Math

• glew, opengl extension managements
• glm, simple vector math library

Other

• cxxopts, command line argument parsing
• rapidcsv, for parsing csv files in the external tools
• tinyobj, for parsing obj files
• magicenum, to improve the serialization of enumeration types
• stb: small library used to load images

Building

Building CassettePlayer and the tools should be as simple as running 2 commands

cmake -B build -DCMAKE_BUILD_TYPE=RELEASE
make -j4 -C build

This will download and build all the dependencies required (except for wxWidgets). The main app and all tools should then be compiled into the appropriate directories in the build folder. Please switch to debug mode for development, by changing RELEASE to DEBUG.

Running the App

Once the app is built and the datafiles are created, the app can be run simply with

./build/src/App

Upon launching the application, you will be prompted to either load an existing assembly, or create a new one. All of this is driven by the information in the configuration files. If you already have such files, you can simply launch the App and get started.

If you need to produce or modify configuration files, please read on.

Configuration and Assembly Files

CassettePlayer is quite driven by configuration and data files found in the resources directory (current just resources).

Resource Layout

Within the resources folder there are the following directories

• component_library: Here is where all the component descriptions should go, as well as any .obj files needed to describe their geometry.
• geometry: Temporaily, this is where the geometry files from hgcalmodmap are kept.
• cassettes: Folder containing the descriptions of each cassette
• scripts: Folder containing the user defined scripts

Assembly Architecture

The current architecture for the system is based on components and slots.

A component represents some some type of part in the assembly. A component can optionally be associated with a some model file if it needs to be rendered. Components can be defined to have different fields, containing the type int, float, string, or slot. The purpose is these fields is that when the designer creates an assembly, they may use these fields to specify information about the slot. For example, consider the component definition for a certain wagon

{
    "ID": "East3",
    "Fields": {"Engine": "Slot", "LR": "Int"},
    "Layers": ["Wagons"],
    "ShortFormat": "Wag(E {Engine})",
    "LongFormat": "Wagon attached to engine {Engine}",
    "NeedsBarcode": true,
    "Model": {"nullopt": false, "data": "East3"}
}

We can break down this information.

• ID: Unique id for this component, used in the slot system to tell the slot which component type it has.
• Fields: the data associated with the component. Here this wagon is defined by the Engine it is attached to (which will be a slot in the assembly), and some integer information about it orientation.
• Layers: These are used mostly in the visualization.
• Formats: String formats, used to display the a slot textually. When a slot to be shown as text, it looks at the formatting for its component type, and fills the format fields with the values.
• NeedsBarcode: Whether this is a component which needs a barcode. If it does, then in the assembly application the user will need to provide a barcode when informing the application that a component has been placed.
• Model: If using a rendering for this component, then this is the model used. For example, to find out how to draw the East3 wagon, the application will look for a file called “East3.obj” in the component library

Now a component on its own is useless, it only defines how information should be used, not so much what it is. This is where a slot comes in.

A slot represents an instance of a component being used in an assembly. The most important aspect of a slot is its associated component. Lets look at an example

{
 "ID": 68,
 "Component": "East3",
 "SubAssembly": false,
 "Data": {"Engine": "o:58", "LR": "i:0"},
 "Position": [1506.96997, 580.03002, 6.0],
 "Orientation": [0.0, 0.0, 0.0]
}

The “assembly information” associated with the cassette is

• ID: a unique id defining the slot.
• Component: what type of component is this slot
• Sub-Assembly: currently unused
• Data: Values for the data fields as defined by the component. The prefix can be “o”,”i”,”f”, or “s”, indicating that this should be interpreted as a slOt, Int, Float, String. For example, this slot is an east3 wagon attached to the engine slot with ID 58.

Additionally, each slot has rendering information

• Position: where in physical space the slot is, in x,y,z coordinates.
• Orientation: its orientation in physical space as Euler angles.

About the model files

The model information is stored in the standard wavefront object file format. Many editors should be able to import and export this format. If you need to write your own object file, you can use a 3d editor, or do it by hand (since most of these object have very few vertices).

For Developers

In this section we provide a brief description of the design (or lack thereof) of different components.

Sublibraries

The core libraries, found in folders under src at the time of writing are: assembly, visualization, scripting, gui, vmath, and common.

Assembly

This is data layer of the assembly application. It contains the classes and functions used to describe the assembly process, the current state, and more.

A note on serialization

A recurring feature throughout the application is the use of Handle<T> and DataManager<T>. These two classes work together to provide a thin wrapper around raw pointers, with the most important feature being that they allow the serialization of pointers in a user readable format. Specifically, each type T must provide a member id. When a Handle<T> is serialized, it stores the value T::id. When deserializing, the handle is constructed with the appropriate id variable. However, it does not yet have a pointer to the actual object. This is the purpose of DataManager<T>. This class manages the lifetime of its contained T. We can relink the Handles with their underlying data through the Handle<T>::relink(DataManager<T>) which uses the id to find the correct memory.

Visualization

This library provides the Visualization frame and associated classes that allows the rendering of different components.

Scripting

This library integrates lua scripting and creates lua usertypes for important assembly classes.

GUI

This is the library that forms the user facing part of the application.

Common

Common contains a growing collection of useful utilities.

VMath

Vector mathematics, effectively a using alias over glm types. Also includes some functions for printing and serializing vector types.

Initialization and Lifetimes

The initialization process of the app is somewhat complicated. The majority of the major components are assumed to have the same lifetime as the app. Specifically, when we load the components or assemblies in to the app we must ensure the exist for the entire duration of the assembly window. When loading OpenGL, special care must be taken with GTK, since the GLCanvas must be fully opened and visible before any OpenGL functions are called.