Tball v1.0 Release Notes

Tball is a software specifically developed by RayInstitute for tracking LED kinetic ball with laser. Tball is entirely based on three-dimensional physical space algorithms for laser tracking. It can track based on the lifting speed of different lighting fixtures, thus achieving precise tracking based on four-dimensional parameters (three-dimensional position plus mechanical performance parameters).

 Highlights :

1. On the hardware side, Tball also directly interfaces with Beyond, outputting laser data to the corresponding Zone of Beyond. Therefore, the hardware used for connecting the laser is also the official hardware from Beyond, either the FB3 or FB4 box.

2. On the software side, Tball supports Artnet signal input and output. The input signal is used for real-time calculation of the three-dimensional position of the LED ball and to output tracking points to each laser light. The output signal is used for direct effect testing during debugging. It supports simulation rendering using D2 or D3 software.

The default channel map for the LED kinetic ball uses the built-in kinetic ball fixture profile from Depence, but you can also modify the channel map as needed.

Since the software implements laser tracking based on three-dimensional physical space algorithms, you will need to use a laser rangefinder to accurately measure the hanging position of the LED ball and the three-dimensional position and angle of the scanner in each laser during on-site debugging.

In the software, you can align the LED ball unit in linear, grid, or circular patterns, and you can also make individual position fine-tuning for each LED ball.



The software is organized around the concept of Artnet Universes to segment units. Each universe, which consists of 512 channels, forms a unit that includes LED balls, the lasers tracking these LED balls,  and associated parameters. If you need to use the same laser for tracking across different universes,  you simply need to assign the same Beyond output Zone to the laser in the different units.

Here’s a breakdown of the software interface:

– The left side of the software is dedicated to the LED balls debugging area.

– The center features the effect preview screen.

– The right side is for unit settings, output configurations, and UI-related settings.

– The upper right corner is the logo area, and the top right corner displays the software’s running frame rate. It’s important to ensure that your computer’s hardware is capable of running the software at a frame rate of over 30 FPS.

– The project save button is located at the logo circle, allowing you to manually save project files.

– The lower right corner of the software features the coordinate system navigation icon. The software uses a right-handed coordinate system (where the blue Z-axis is positive towards the operator), which is opposite to the left-handed coordinate system of Depence, particularly regarding the Z-axis direction. Therefore, when simulating with Depence, you will need to invert the Z-axis coordinates accordingly.

For Depence simulation, I will provide example files that include a modified kinetic ball fixture profile and a laser fixture profile. You can also compare the fixture positions and corresponding rotation parameters in the Tball software as a reference.


The software interface is designed with intuitive controls and a variety of ways to interact with and adjust the parameters. Here’s a detailed explanation of the interface and its functionalities:

– **Parameter Adjustment Areas**: You can expand or collapse the parameters of each section by clicking the up and down arrows on the far left of all white title bars. The left and right arrow buttons on the outer sides of the top title bars are used to show or hide all parameters for the corresponding sections.

**Button Colors and Functions**:

  – **Cyan Buttons**: These are toggle buttons, which means they switch the state of a setting on or off when clicked.

  – **Orange Buttons**: These are push-type buttons, such as the fixed color button, which perform an action when pressed.

  – **Tan Text**: This represents parameter labels.

  – **Light Yellow Buttons**: These are multi-select buttons, allowing you to choose multiple options.

  – **Yellow Text with a Purple Background**: These are single-select buttons, where only one option can be chosen at a time.

  – **Purple Parameters**: These are global parameters that are uniform across the software, such as the selection of the local address.

**Adjusting Numerical Parameters**:

  – You can adjust numerical parameters by scrolling the mouse wheel over them.

  – You can manually input data into the numerical fields.

  – Holding down the left mouse button on a numerical input field will bring up a differential adjustment menu.

  – Placing the mouse cursor over the adjustment area allows you to fine-tune the values by moving left or right.

  – Right-clicking on a parameter slider will reset the parameter to its default value.

– **3D View Operations**:

  – The middle 3D view operates similarly to other 3D software.

  – Use the mouse wheel to zoom in and out of the view.

  – Hold the right mouse button to pan the view.

  – Use the left mouse button to rotate the view.

  – With the appropriate selection options enabled, you can also use the mouse to select lasers and LED balls and adjust their parameters.

– **Keyboard Controls**:

  – The controls are similar to those in gaming engines.

  – The ‘A’, ‘S’, ‘D’, and ‘W’ keys allow for left, down, right, and forward movement of the view, respectively.

  – The ‘Q’ and ‘E’ keys are used for up and down movements.

  – The ‘H’ key resets the view to the home position.

  – The ‘L’, ‘R’, and ‘T’ keys switch to left, right, and top views, respectively.

– **Space Settings in the Right Area**:

  – You can toggle the display of the coordinate axes and adjust UI-related parameters here.

– **Project Saving**:

  – In the UI settings, there is a field where you can enter the name of the project you wish to save.

  – Clicking the save icon will save the project with the specified name in the project’s folder.

  – You can reopen the project by simply double-clicking the saved file.

Debugging Process:

1. Unit Setup and LED Ball Align:

Upon opening the software, there is a default Unit 1. You can find the settings for the unit on the right side of the interface under Units Settings. Click the Unit + button to add a unit , and the Unit- button will delete any units greater than 1.

You can adjust the number of LED balls within Unit1 on the right side of the LED balls settings bar. Keep in mind that the number of channels occupied by the LED balls in each unit must not exceed 512 channels.

The unit position parameters refer to the global coordinate origin of the current unit. The positions of all LED balls and lasers within the unit are adjusted based on this position. By default, it is set to the coordinate origin. When you are on-site for debugging, you should first determine the position of this coordinate origin, as it is related to the measurement of the coordinates of the LED balls and lasers.

Adjusting the unit rotation parameters will rotate all LED balls and lasers within the unit based on the unit’s coordinates.

Next, perform the arrangement operation for the LED balls within the unit. When the Select All button is activated, the select range bar is disabled, and the arrangement will be applied to all LED balls within the unit. If you only want to arrange a subset of the LED balls within the unit, you can deactivate the Select All button and enter the desired range in the Selection Range bar, such as 1-10 to arrange the LED balls with ID numbers 1-10.

After adjusting the corresponding X-axis and Z-axis ranges, click the Line Align button to arrange the balls linearly within the specified range on the corresponding coordinate axis. For example, setting the X-axis range to 10 will arrange the balls within the range of -5 to 5 meters on the X-axis.

To arrange in a grid pattern, first adjust the number of columns for the grid align, then click the corresponding Grid Align button. Note that the X-axis and Z-axis ranges should also be adjusted accordingly to achieve a grid-like arrangement within the specified range.

For circular arrangement, simply adjust the number of circular arrangement rings, the base radius, and the radius offset, then click the Circle align button.

2. LED Balls Parameter Settings:

After arranging the LED balls, you can then set the parameters related to the balls on the left side of the interface.

Ensure that the lifting distance and speed are consistent for all LED balls within a unit, as all parameters in the LED ball unit settings are global parameters. If the kinetic balls are far from the control desk area, there may be corresponding signal delays. In this case, you can adjust the delay time to match the laser signal with the lifting ball signal. Usually, you can keep this delay parameter at 0 when simulating in Depence.

Each unit of LED balls can adjust the global hanging position of the ball unit through the BallsPos option, mainly by adjusting the Y-axis, which is the height value. This height value is the position of the center of the ball when it is fully lifted. When debugging on-site, you only need to measure the height value of the bottom of the ball plus the radius of the ball. In Depence, you can place a ball object at the position of the lifting ball to obtain the actual height of the ball.

The mechanical lift speed unit is meters per second. You can find this in the settings options for the corresponding fixtures in Depence. Next are three toggle buttons that can switch the display of each ball’s ID and DMX address in the 3D view. When enable pickable activated, you can use the mouse to directly select a single ball to set the corresponding parameters. Font size refers to the font size of the ID and DMX address.

The default channel count for the LED kinetic ball is 5 channels, which is based on the kinetic ball fixture profile in Depence. The default starting channel for the LED ball unit is 1. When the 16-bit lift channel is enabled, it will automatically set the fine-tuning channel for the lift channel to the next channel, such as the default lift channel being 1 and the 16-bit fine-tuning channel being 2. You can map the remaining related channels based on the actual channel table of the fixtures used, and after setting up, click the SetChansMap button to complete the channel table mapping.

3. Effect Testing and ARTNET Control:

After setting the channel table mapping, if your computer has an ARTNET box that can directly control the actual kinetic balls, you can directly use the effect test area on the left side of the interface. Click the DMXOutput button to enable the sending of ARTNET signals. Usually, you do not need to specify the local network card. If the output is not normal, you can first turn off the output and specify the network card for the output signal. Once the output button is activated, the Input OFF button in the DMX settings section at the bottom will be disabled, and the Local Address option will not be available. The ARTNET network card is a global parameter. The Net/Subnet/Uni below can be used to specify the universe for each unit to receive and send Artnet signals.

4. Effect Testing:

The effect test part is only used to test the basic functions of the kinetic balls to ensure they can operate normally.

After activating the Enable Output button, clicking the Fixed Color button will automatically set all the LED balls in unit to the corresponding color. You can change the RGB parameters at any time, and their range is 0-1, with the changes displayed in real-time on the right side.

Clicking the Color Effect button will automatically apply an effect similar to the color channel of the kinetic balls. You can change the effect’s pattern period, pattern width, and running speed. When the speed is set to 0, the effect can be paused.

Clicking the Fixed Height button allows you to adjust the height of the kinetic balls by combining the  offset and height. When the offset is 0, the height slider value is the running height of the kinetic ball. Of course, this height value is not the actual height. The actual height needs to be combined with the Ball Unit Position and Unit Position parameters above. If the height is adjusted to 0, it means the kinetic ball has descended to the lowest position. If the value exceeds the lift range of the kinetic ball when adjusted upward, it will not take effect.

5. Laser Light Parameter Settings:

Next, let’s set the parameters for the laser lights. In the laser settings section, the first part separated by a horizontal line is the global settings within the unit. After activating the track Enable button, the lasers will be assigned to track all the kinetic balls in the unit. If you only want each laser to track different kinetic ball, do not activate this option.

After activating the Enable pickable button, you can directly use the mouse in the 3D view to select the laser to set different parameters for individual lasers. When the Display Label option is activated, the outlet of each laser in the unit will display its unit number and its own number in the 3D view. This way, you can understand the rotation status of each laser. The Laser Color section is used to set the shell color of the laser lights in the 3D view.

Laser intensity is used to adjust the output brightness of the lasers within the unit. For Depence simulation, reducing the brightness value appropriately will be more expressive. The Laser Angle here should be adjusted according to the specific angle value of the laser you are using, with the default value being 60 degrees.

The Sample Rate should also be set according to the scanning rate of the scanner in the laser you are using. The Step Size and Vertex Hold values can usually be kept at their default. The smaller the Step Size, the more points can be drawn, of course, this is affected by the scanning rate of the specific laser’s scanner. The larger the Vertex Hold, the brighter each point will be. The default values here are set according to the performance in Depence software. In actual use, you can adjust according to the actual performance of the laser.

In the following section, you can use the Laser + and Laser – buttons to manage the number of lasers. By selecting different lasers, you can set different positions and rotation parameters for each laser. When debugging on-site, first determine the 3D position of the laser scanner relative to the coordinate origin and a rough rotation angle value. For on-site debugging, we can then use the options in the effect test section to activate the led balls or use the console to light up the led balls. Then, in the single ball settings on the left side of the interface, assign different lasers to each ball. In actual use, some kinetic balls may be obscured by other kinetic balls and not suitable for tracking by a specific position laser. The specific approach is to use the principle of proximity to assign lasers to each kinetic ball.

When you turn off the Track Enable button in the laser settings on the left side of the interface, remember to turn on the Track Enable button for the kinetic balls that need tracking in the single ball settings section.

In the single ball settings section, you can also make fine adjustments to the position of individual LED balls, including specifying different DMX addresses. Be careful not to conflict with other addresses.

After assigning the lasers, let’s activate the Beyond Enable button to send tracking points to Beyond, remembering to set a different Zone for each laser. You can click the OpenView button in the laser settings section to activate the tracking perspective of the corresponding laser, making sure that the kinetic balls being tracked by this laser are within its tracking range when moving up and down. If there are any that exceed, you will need to reconsider the position and angle of the laser.

When you are sure that the kinetic balls being tracked by each laser are within its field of view, then adjust the angle of each laser light to ensure that the on-site laser tracking points are accurately aimed at each lifting ball. At this time, it is best for the position of the kinetic balls to be random. Similarly, after adjusting the rotation angle of each laser, we can let the kinetic balls move to determine the actual tracking delay time and make fine adjustments to ensure the final perfect tracking effect.

Development Plan:

The software currently implements core foundational functionalities, and further enhancements are planned to add more playful effects in the future. For instance, there are plans to include separate control features for the kinetic balls and laser colors, as well as interactive radar functions for the kinetic balls. 

Additionally, We encourage everyone to share their ideas and thoughts in the comments section.


Leave a Reply