ButterflyFleet Studio for Blender User Guide

ButterflyFleet Studio for Blender consists of multiple modules that are interpreted by the Python interpreter built into Blender. In order to perform an upgrade of the add-on, the previous version needs to be unloaded completely before the new version is installed. Due to how Python’s module system works, this is very hard to do without unloading the plugin manually. Therefore, the preferred sequence to update the add-on is as follows:

If you decide to uninstall ButterflyFleet Studio for Blender for any reasons, you have to do it manually. Removing the add-on from Blender’s add-on manager is possible, but it will not remove all files related to ButterflyFleet Studio for Blender. The full, manual process is as follows:

Blender uses relative time and this is preserved in the exported ButterflyFleet compiled show files as well. Frame 0 in Blender becomes relative time 0 s in the .skyc output.

Blender uses a relative coordinate system with X, Y and Z axes. The real world has directions of North-South, East-West and Up-Down in geodetic coordinates (latitude, longitude, altitude).

The add-on lets you store optional real-world placement metadata in the exported show according to the following rules:

The table below summarizes all mappings between the relative and absolute coordinate system.

A typical drone show starts with the drones being arranged in a grid-like pattern on the ground. The spacing of the grid is usually between 2 to 4 meters, although it can be even smaller in crowded urban areas where it is hard to find large open spaces. A regular grid is easy to set up, but in certain cases it is more beneficial to shift every second row of the grid by half of the grid spacing to increase the distance between drones a bit further.

ButterflyFleet Studio for Blender will place the drones in a regular grid by default, but you can freely adjust the initial positions of the drones as needed to adapt the takeoff grid to the requirements of the area where the show will be performed.

Most drone shows alternate between showing static or dynamic formations (where the drones are arranged in patterns resembling familiar shapes, objects, animals or corporate logos) and performing transitions between the formations. Formations are designed and choreographed artistically, while transitions are typically computed by a path planning algorithm that knows how to make the drones move from the end of one formation to the beginning of the next formation while keeping safe distances between drones to avoid collisions.

In ButterflyFleet Studio for Blender, formations are stored as sub-collections in a top-level collection named Formations. This is a convention that you need to stick to; ButterflyFleet Studio will always look for this collection by name, and it will create one if it does not exist yet. Make sure not to rename this collection. Each sub-collection of the Formations collection is an individual formation, also identified primarily by its name so make sure to use unique names. The objects in a formation may be:

We call the desired positions of the drones within a formation markers. Recall: markers may be the origins of empty or non-empty meshes, or the vertices in a dedicated vertex group of a mesh. It is possible to mix the three types of markers within a single formation, although the most common case is that either you have a number of empties in a formation, or a single mesh where a subset of vertices of the mesh are placed in a vertex group named Drones.

ButterflyFleet Studio for Blender arranges the formations into a list that we call the storyboard of the show. Each entry in the storyboard consists of an arrival frame when the formation should appear on the sky, a hold time, and a reference to one of the formations in the Formations collection. For entries after the first one, the previous entry’s depart frame is also the transition start for the incoming transition. Entries may not overlap with each other and one should ensure that there is enough time between formations to perform a transition. In a typical show, transitions last between 15-30 seconds, depending on the maximum velocity of the drones and the sizes of the formations.

When the show timeline is within the arrival and depart frames of a storyboard entry, ButterflyFleet Studio for Blender ensures that the drones follow the formation markers using standard Blender constraints. When the show timeline is between two formations, ButterflyFleet Studio for Blender will smoothly animate the influence parameters of these constraints automatically to make the drones fly from one formation to the next one. The assignment between drones and markers is calculated by the configured planning backend when you click on the Recalculate Transitions button on the storyboard panel.

Automatic transitions between two formations are calculated by the configured planning backend in the background using highly-optimized proprietary maths. ButterflyFleet Studio for Blender provides automatic transitions between static, non-staggered formations with the following guarantees:

Note that the automatic transition planner tries to find an optimal matching between source and target formations even in dynamic (nonzero starting or ending velocity) or staggered (different starting or ending time of different drones) cases, but without minimum distance guarantees, for the time being.

A drone show does not end with the last visible formation on the sky — one should also bring the drones back to the takeoff area in a safe manner. This is typically done in two parts: the return-to-home (RTH) maneuver makes the drones fly back above the takeoff area to a designated altitude, while the landing maneuver lands them vertically to ground level. In ButterflyFleet Studio for Blender, the RTH maneuver is planned as a collision-free return to assigned slots in the takeoff grid, with optional layered timing. For ground-to-ground shows, add a landing entry after RTH so the exported trajectory reaches ground level and is ready for the target flight stack’s normal end-of-show behavior.

ButterflyFleet Studio for Blender also supports flawless light design for your drone light shows. In Blender we support a single RGB color to be mapped to each drone at each frame in the timeline by simple baked colors or by complex parametric light effects overlayed to the base color. The RGB color output from Blender is stored in exported show data for later conversion to the LED color space required by the target hardware. There are several smart tools dedicated in ButterflyFleet Studio for Blender for light design, to see these options please checkout the description of the LEDs tab.

ButterflyFleet Studio for Blender supports pyro control as part of your drone light shows. Pyro trigger events on multiple channels can be created with convenient payload descriptors and different visualization types. Pyro control events can be exported into the main .skyc show file or into external formats supporting drone-launched pyro. For more information please checkout the description of the Pyro tab.

ButterflyFleet also supports yaw control as part of a drone show for certain drone types. The yaw angle for yaw control in ButterflyFleet Studio for Blender is simply inferred from the Z component of the global rotation of objects assuming "XYZ Euler" notation. So far there are no specific tools to aid yaw control, it is the responsibility of the designer to create a yaw curve that harmonizes with the concept and spatio-temporal trajectory of the show.

To export yaw control for your show, check the "Export yaw" checkbox in the .skyc export panel.

We suggest you to check the following Blender settings before you start designing your drone show:

Press N in the 3D Viewport editor to open its sidebar.

You will see six new tabs related to ButterflyFleet Studio:

These tabs contain all panels, buttons, operators and functions that are specifically needed for drone show design, in proper order.

The first two panels of interest are the Show panel and Swarm panel on the ButterflyFleet tab.

These panels contain some general configuration options you might want to review before starting your actual design workflow.

After configuring your workflow, move to the Formations panel on the Formations tab.

To initialize your drone show, first of all, press the Create Takeoff Grid button on the top of the Formations panel and check out the parameters in the popup window.

Setup your takeoff grid with any convenient parameters and press OK.

This will create all ButterflyFleet-specific collections (Drones, Formations and Templates) that you will need for your drone show, will add the first "Takeoff grid" entry to the storyboard and will also initialize your drones in the 3D Viewport editor.

To learn more about the mentioned collections, please read the Key concepts and the Glossary.

Drone shows typically consist of artistic formations and other technical parts that are usually not the responsibility of designers to deal with (such as takeoff, transitions between formations, return-to-home or the landing procedure). ButterflyFleet Studio provides automated tools for handling these parts, if needed.

To take off your drones, simply press the Takeoff button on the Formations panel and setup the parameters of the automatic takeoff procedure.

After you press OK on the Takeoff popup window, the "Takeoff" entry should appear in the Storyboard panel as the second entry.

Formations are standalone parts of your final drone show, consisting of static or dynamic (animated) scenes.

The Formations panel will be your guide to deal with formations.

Use the + button on the Formations panel to create a formation as part of your drone show.

If you would like to create static formations, they can be initialized from many individual objects (one drone per object) or from selected vertices of a single mesh (one drone per vertex).

If you wish to create animated formations, you have two options:

Either way, make sure that the number of markers (vertices or objects) you use in a formation matches the size of your fleet. If your formation uses less markers than your fleet size, supplement it with placeholder objects so ButterflyFleet knows where to send the extra drones that do not participate in the formation., If your formation contains more markers than the number of drones in your fleet, ButterflyFleet will complain loudly when you try to recalculate the transitions between the formations.

Repeat this phase with all the formations of your drone show and create a separate formation collection for all of them. These collections will all be listed in the Formations collection in the Outliner.

The storyboard defines the temporal structure of your drone show, consisting of formations coming one after another, with automatic or manual transitions between them.

Check out the Storyboard panel in the Formations tab.

Add your formations to the storyboard, define their arrival frames and hold times. Leave the transition type as Auto and the transition schedule as Synchronized for the time being to let ButterflyFleet attempt to calculate the transitions between them. Later on you can experiment with more advanced, Manual and Staggered transitions, too.

Use the Recalculate transitions button at the bottom of the Storyboard panel of the Formations tab to create optimal transitions between your formations automatically. This will assure that all drones from a starting formation are mapped to their optimal matching point in the target formation.

While transitions are created, your drones in the Drones collection will also be attached to all your formations. The animation part of your show is now almost ready…

After all your artistic formations are ready, press the RTH and Land buttons on the Formations panel in the Formations tab to add automatic return-to-home and land procedures to your drones, the same way you added the takeoff procedure at the beginning.

Popup windows for each button appear to be able to setup the parameteres of these smart functions. On success, the proper entries should also appear at the end of your storyboard.

Use the Safety Check panel in the "Safety & Export" tab in the sidebar of the Viewport editor to enable real-time verification checks on your animation.

Setup your safety parameters with convenient values and watch your animation in the 3D Viewport editor. Drones and drone pairs not passing the safety checks (velocity, altitude, proximity) will be highlighted with red, while status information about the verification results will be visible on the left side of the window.

Press the Validate Trajectories button to get a full validation for a frame range, not just for a single frame (this might time some time depending on the number of your drones and the number of frames selected). Review the generated validation output and correct any trajectory, velocity, altitude or proximity issues before export.

Correct your show to eliminate all safety check warnings to ensure maximal safety of your drones and the world below them…

After all your animations are finalized and verified, use the LEDs tab in the sidebar of the 3D Viewport editor to add light animation to your show.

The first panel of interest for light design is the LED Control panel.

Move the scene to the desired frame, select the drones you wish to paint, select a color or two colors and press the Apply (change abruptly) or Fade to (fade linearly from last keyframe) buttons to add color animation keyframes to the given drones at the given frame.

As a more advanced option, use the Light Effects panel in the LEDs tab to create more sophisticated, parametrized light effects for your show.

The effects defined in the "Light Effects" panel are calculated on-the-fly, frame by frame in Blender, based on several criteria, including the positions of the drones and an optional associated mesh, so it is possible to create light effects where the color depends on how far the drones are from a certain mesh in the scene or whether they are inside or outside an invisible "helper" mesh.

There are additional options to make your drone shows even more spectacular, such as adding drone-launched fireworks to your shows or enhancing visuals with controlling the yaw angle of drones.

For adding pyro control please checkout the description of the Pyro Control panel.

For adding yaw control to your drones please use any standard Blender tools to change the orientation of your drone objects according to your needs.

Once ready with both the animations and light program, use the Export to .skyc button of the Export panel on the "Safety & Export" tab to export your entire show into ButterflyFleet compiled show format.

The ButterflyFleet compiled show format stores the sampled trajectories, lights, yaw, pyro and metadata needed for the final show file.

The Export to .csv button of the Export panel allows you to sample the drone trajectories and the corresponding RGB colors at regular intervals and save them to a CSV file that you can load in external tools for further post-processing.

The Export to validation .pdf button creates a unique safety report of your show in .pdf format for self-checking, validated reporting or as a supplement for flight permissions.

If you are a professional license holder, please press the Refresh file formats to get a full list of additional third-party export formats that your license supports.

We are done. Review the exported .skyc file and send us feedback or ask us if you have any questions!

There are certain standard Blender settings (e.g. the Viewport shading color and wireless color option in the 3D View panel) that need to be setup properly to make the ButterflyFleet Studio for Blender addon fully functional. With pressing this button, all necessary Blender settings are updated to support the latest version of ButterflyFleet.

If you load a previous Blender file created with an older version of ButterflyFleet Studio for Blender, press this button to initiate a migration to the latest version.

Please specify whether you designed a show for outdoor or indoor settings. This will help setup drone size, exporters and possibly other parameters adaptively.

Selects the transition planner used by the server for automatic transitions:

Controls the request-level bucket-matching override used during transition point matching. Use server_default to follow the server configuration, disabled to turn bucket matching off for this request, or choose a concrete matcher used inside adaptive buckets: fast, sorted, greedy, hungarian, depth_polar, polar_sorted, sector_plus, depth_balanced, collision_aware, nearest_collision_aware_optimal, radial_sorted, sector_radial_sorted, pca_rank_sorted, centroid_frame_optimal, shell_preserving_optimal, sector_shell_optimal, topology_aware_optimal, graph_topology_optimal, neighbour_fast, neighbour_sorted, or neighbour_depth_balanced.

The orientation section provides controls for yaw visualization and the spatial reference of the show.

If you know the exact location and orientation of your show in the real world, you can give this information to the add-on to include it in your exported .skyc show file as placement metadata. If you want to propose values for show origin and show orientation, enable the Specify location checkbox.

Click on the Drones button to select the collection that is your primary source of your drone objects. By default you do not have to change this setting, the Create Takeoff Grid button below will create a "Drones" collection and set it as your primary source automatically.

The Preferred acceleration slider sets a preferred acceleration (in all directions) that is used by the automated motion planning functions of ButterflyFleet Studio, for example when automatic transitions or transition times are calculated.

The panel includes three sliders that control the final phase of the landing trajectory:

Before creating your first takeoff grid that initializes your drone objects, you can select a template object for your future drones. There are three options to select from, given by the Drone template drop down menu.

The default option is an isotropic Sphere. Select Cone to have a simple anisotropic object (suitable for yaw-controlled shows), or select Selected Object for any custom object that will be used as your drone template.

If Selected Object is chosen, make sure you have your template object selected before pressing the Create takeoff grid button. Note that this object will disappear after the creation of the swarm as it shall be used for the template only.

If you select a "Sphere" or "Cone" type drone template, you can also setup a radius for your template object before creating your first takeoff grid. The field is editable for the built-in Sphere and Cone templates. When the template is set to Selected Object, the selected object defines its own size and the radius field is disabled.

If you wish to change your drone size at a later stage, you can use standard Blender tools for this. First select all your drone objects you wish to resize, then set the "Transform Pivot Point" to "Individual Origins" and the simply scale up all objects around their own origins with s.

The Create Takeoff Grid button helps you set up your first and last formations, the takeoff and landing grid. The takeoff and the landing grid is assumed to be the same by default, but you can change them later on if needed.

For a regular takeoff grid you can define the number of rows and columns, the exact number of drones and the spacing between them. Once you press OK, a rectangular grid is created with the specified parameters.

For advanced settings enable the Advanced checkbox.

If you wish to have a separate column and row spacing for your basic takeoff grid, enable the Use separate column spacing checkbox and setup a separate column spacing.

If you wish to takeoff (and land) in layers, you can also define a more complex takeoff grid with slots, where each slot contains more than one drone with typically, but not necessarily smaller spacing (see the Intra-slot parameters). With such a takeoff grid it will be guaranteed that only one drone will takeoff from (and land to) every slot at a time, using layered takeoff and land operations automatically.

The Create takeoff grid operator also creates all ButterflyFleet-specific collections (Drones, Formations, Templates) that you will need for your drone show, it adds the first "Takeoff grid" entry to the storyboard and also initializes your drones in the 3D Viewport editor.

The Takeoff button adds a takeoff maneuver to a specified altitude and with a specified average vertical velocity from your initial takeoff grid. The start frame of the maneuver can be customized, although it is usually the same as the first frame of the scene.

If the minimum distance between drones in the takeoff grid is smaller than the given spacing parameter, the takeoff is automatically performed in layers with no drones closer to each other than the spacing.

In such cases (i.e., when you set a small spacing parameter or the takeoff grid was created with more than one drones per slot), use the layer height parameter to setup the altitude difference between additional target layers above the default layer during the layered takeoff operation.

This button should ideally be pressed right after the takeoff grid is created, but before any other formations are added. It is also possible to use the operator later after having defined the first few formations, but you must ensure that there is enough time before the first formation to perform the takeoff and get to the first formation in time.

The RTH button adds a smart return-to-home maneuver that brings drones from their positions at the end of the last formation to assigned slots in the takeoff grid, using collision-free path planning. The maneuver is performed at a specified average horizontal velocity (XY) and vertical velocity (Z), arriving at the given altitude above the takeoff grid.

If the minimum distance between drones in the takeoff grid is smaller than the given spacing parameter, the RTH operation is automatically performed in layers with no drones closer to each other than the spacing.

In such cases (i.e., when you set a small spacing parameter or the takeoff grid was created with more than one drone per slot), use the Layer height parameter to set the altitude difference between additional target layers above the default layer during the layered RTH operation.

The operator dialog lets you configure:

Note that the maneuver is not performed at the specified altitude — it is initiated from the positions at the end of the last formation. However, all drones arrive to the given altitude (or layered altitude) value, above the takeoff grid.

This button should be pressed after all formations of the show are inserted to the storyboard, but before the landing entry is given.

The RTH path plan is computed by the configured planning backend using the layered_checkerboard algorithm, which guarantees collision-free trajectories down to the home grid while respecting the configured velocity, acceleration and minimum distance constraints.

The Land button lands the drones, starting from a given frame such that they move downwards in a straight line from their current position until they reach the given target altitude (ground is assumed to be at Z = 0). As usual, the average velocity of the descent can be adjusted.

If the minimum distance between drones in the takeoff grid is smaller than the given spacing parameter, the land operation is automatically performed in layers with no drones closer to each other than the spacing.

In such cases (i.e., when you set a small spacing parameter or the takeoff grid was created with more than one drones per slot), use the Motor spindown delay parameter to setup the time difference between landing layers. This ensures that drones will land close to the others within the same slot only when the motors of the neighboring drones are already stopped.

This button should be pressed after the return to home entry is inserted to the storyboard.

Click on the Formation button to select the formation to be edited in the Formations panel.

The + button creates a new formation. Remember that formations are essentially sub-collections in your Formations collection, consisting of (stationary or animated) markers that define the desired positions of the drones in a particular scene of your drone show.

You can define a name for your new formation and choose how it should be initialized:

When the number of markers in the created formation is different from the number of drones in the show, a warning message will appear to indicate the formation size mismatch.

If you see such a message, try to harmonize the number of markers in the formation with the number of drones in the show, otherwise automatic transitions won’t work.

Press the ✕ button to remove the selected formation from the Formations list and the Formations collection entirely. Meshes that were part of the formation but that were not referenced from anywhere else in the Blender scene will also be removed from the scene. If you want to keep them, put them in another collection first or by assigning them to a fake user in Blender.

The Select button on the Formations panel adds the selected formation to the current selection in Blender. Similarly, the Deselect button removes the markers of the selected formation from the current selection.

Since formations may contain meshes as well as vertices of meshes as markers, you may not necessarily see the result of the selection immediately. If you are in Edit mode and you attempt to select a formation that contains meshes, you need to switch back to Object mode. Similarly, if you are in Object mode and you attempt to select a formation that contains vertices a markers, you need to switch to Edit mode to be able to interact with the selected vertices.

Once a formation is created (and preferably appended to the storybard), use the Generate Markers button to generate extra static or dynamic markers into that formation from different sources:

Press the Update button to update the selected formation from the current selection or from the current positions of the drones. This operation is essentially equivalent to removing all markers from the formation first, followed by the addition of the selection as if you were creating a formation from scratch.

You can also update formations simply by moving the markers in 3D space using the standard tools that Blender offers. New markers can be added simply by creating empty or non-empty meshes and adding them to the appropriate sub-collection of the Formations collection, or by extending the Drones vertex group in vertex-based meshes. Unneeded markers can simply be removed from the formations the same way you would remove any Blender object from its corresponding collection.

Points in every formation have a specific order. This gets useful when staggered transitions are created between two formations and thus drones do not depart from or arrive to a given formation at the same time, but in a delayed manner, one after another, in the order they are represented in the formations.

Reordering a formation can be issued any time with opening the Reorder drop down list and selecting the preferred reordering operator. Note that reordering is instantaneous; using multiple reorder operators is possible, each one will take the current order and apply its own modifications to create the new order. The following reorder operators are implemented:

Press the Stats button to show various useful statistics about the selected formation, such as the number of markers (empties, meshes or vertices), the size of the axis-aligned bounding box of the formation, or minimum distance between its markers on the current frame.

Press the Append button to append the selected formation to the end of the storyboard. ButterflyFleet Studio will calculate the time needed to move from the end of the last formation to the newly added formation, according to the current acceleration and velocity limits, and set up the start time of the new formation accordingly.

Press the Insert button (located next to the Append button) to insert the selected formation as a new storyboard entry between existing entries, at the current timeline frame. Unlike the Append button, which only adds to the end, Insert creates a placeholder entry at the current frame and shifts all later timeline content (subsequent storyboard entries, light effect timing, markers, object keyframes, and tracked move ranges) forward by the placeholder delta.

The insert operation is transactional:

If there is show content after the current frame, the operation proceeds with the shift automatically. To append a formation strictly to the end without shifting any existing content, use the Append button instead.

Press the + button next to the formation list in the Storyboard panel to add a new entry to the end of the storyboard. The new entry will not refer to any particular formation so make sure you also pick the formation in the editor below the storyboard entry list after adding the entry.

Each storyboard entry has a label and an associated set of properties that define the timing and the transition corresponding to the storyboard entry. The label of the formation can be edited by double-clicking on the storyboard entry in the entry list. The widgets below the storyboard entry list allow you to edit the properties of the currently selected storyboard entry.

Press the - button next to the formation list in the Storyboard panel to remove the selected storyboard entry from the list.

Press the upward pointing thin arrow button next to the formation list in the Storyboard panel to select the storyboard entry that contains the current frame. If the current frame falls between storyboard entries, the next entry will be selected. Pressing this button clears the selection if the current frame is after the end of the storyboard.

Press the ▲ button next to the formation list in the storyboard to move the selected entry up by one slot in the storyboard. Similarly, the ▼ button next to the formation list moves the selected entry down by one slot in the storyboard. ButterflyFleet Studio will automatically adjust the start times of the entries to ensure that they are in ascending order.

Once you are satisfied with your storyboard, you can press the Recalculate Transitions button to create automatic and optimal transitions between your formations without collisions.

The popup menu that appears when clicking on the button offers various options to recalculate all transitions or only a subset of them. The recalculation process also creates or updates the constraints on your drones in your Drones collection to follow the given formations during their associated time interval.

The main cues of the storyboard can be rendered as time markers that appear in the Timeline Editor. To reset all time markers related to ButterflyFleet Studio and update them based on the current storyboard entries, press the Update Time Markers button at the bottom of the Storyboard panel (markers added manually will remain untouched).

The panel provides color pickers for two colors that are called primary and secondary, respectively. Changing the color in the color pickers does not add, remove or modify keyframes yet, they simply indicate your desired colors in the next steps. The primary and secondary colors can be swapped by clicking on the arrow button between the color pickers.

The Apply and Fade to buttons below the selected primary and secondary colors open a popup window that looks like the one on the screenshot below. Both buttons insert color animation keyframes at the given frame for the selected drones, according to the settings in the popup window. They have no effect if none of the drones are seleced.

If the Fade to color checkbox is disabled in the panel, then one keyframe with the original color of the drone is inserted right before the current frame and one with the selected (primary or secondary) color is added to the current frame, resulting in an abrupt color change at the given frame. If the checkbox is enabled, only one color keyframe will be added at the current frame, with linear interpolation on the left (from the past) from the previous color keyframe, no matter where it is in the timeline. This creates a fading effect starting from the previous keyframe.

The "Color to apply" option lets you select which color to apply on the drone in the current keyframe. The straightforward options are the primary and the secondary colors, but there is a third option that creates a gradient between the primary and secondary colors if multiple drones are selected.

In the gradient mode, all the drones in the selection are sorted first according to some criterion. The first drone gets the primary color, the last drone gets the secondary color, and all the drones in between them get assigned to a mix of the two colors according to where they are in the ordered sequence. The "Order in gradient" option defines what the sorting criteria should be. The followig options are available:

Ties are broken according to the order of the drones in the Drones collection.

The Use bloom effect checkbox allows you to enable or disable the bloom effect that is applied to the 3D view. The bloom effect adds a not-so-subtle glow around the drones (and all other bright meshes), but it comes with a caveat: the RGB color that you see in the 3D view is not exactly the same as the RGB color that you apply to the drones but a brighter variant of it. On one hand, the bloom effect can be misleading during a fade-out to black because the fade-out seems to start later (and fade-ins seem to start earlier). On the other hand, this behaviour is in fact a good approximation of how the LED lights behave on a typical show drone.

Every light effect builds on a user-defined color space: a one dimensional color ramp, a two dimensional color image or a custom function:

The light effect that you define in the panel produces one or two numbers between 0 and 1 for each drone, based on selected output mapping functions. The color ramp turns the first, the color image turns both mapped numbers into the color that gets applied to the drone.

Colors on the color ramp may have an alpha component. When the alpha component is 1, the color is opaque — it will replace the original color of the drone. When the alpha component is 0, the color is completely transparent and the original color of the drone will not be modified. Values in between 0 and 1 produce transparency effects — for instance, an alpha component of 0.5 mixes the original color of the drone with the color from the color ramp in equal proportions.

Light effects may be (and usually are) limited in space and time. Time-wise, the light effect affects the drones only from its designated start frame through its end frame. Space-wise, the light effect may affect all drones or only a subset of drones that are within the boundaries of an associated mesh. The mesh may be animated to produce dynamic light effects; for instance, you can "sweep" a cone of light on the drones by creating a light effect that sets the color of the drones to white, and then limiting it to the interior of an invisible sphere that is then swept through the scene.

You may have noticed that the upper part of the light effects panel is occupied by a list. This list contains the effects themselves. In each frame all the effects are processed in a top-down manner, and for each effect, Blender decides whether the effect is going to affect the current frame or not, depending on its temporal and spatial properties. In any given frame, multiple effects may be active, and in this case the original color of each drone (defined by the keyframes of its material) is modified by each active effect in the order defined by the list of effects. This becomes important when the colors of the effects have alpha channels as the output may be a mixture of the original color of the drone as well as one or more active effects.

Use the Effect Type dropdown list to select a light effect based on a color ramp (this is the default setting). In this case, below the list of light effects there are standard Blender widgets to set up the color ramp associated to the currently selected effect in the light effect stack. These widgets work just like any other color ramp editor in Blender, but here is a short summary for sake of completeness:

Refer to the documentation of the Color ramp widget in Blender’s own documentation for more details.

Use the Effect Type dropdown list to select a light effect based on a color image. In this case an image selector input field appears where you can select the image used for the light effect. Further below a secondary output type selector and an optional output mapping selector also appears to be able to take advantage of both dimensions of the image as parametric input.

The most trivial usage of a color image is where e.g. the X axis represents time (TEMPORAL output type) and all pixel columns along the Y axis at a given X represent "discrete color ramps" for different time instants (e.g. using the INDEXED_BY_FORMATION output type). This way color effect design is reduced back to simple color image design that can be performed with any external tool.

Another usage is to project a static image onto the drones in a grid formation, using the properly selected Gradient (...) axis assignments on both axis.

Note that there is no interpolation between pixels in the color image, they are selected for each drone and each frame discretely. Therefore, color images should be used with a width/height that correspond to the selected output mapping perfectly (e.g. same height as the number of drones, same width as the number of frames in the light effect etc.), or they are suggested to be smooth images without sharp edges to compensate for the rounding errors of the discrete mapping. You can also scale up a low-resolution image in an external image editor tool and use the scaled-up version to simulate interpolation.

Use the Effect Type dropdown list to select a light effect based on a custom function. In this case a file can be selected that contains the Python function that will be used as the custom function for the light effect. The file should contain a Python function with the following named arguments:

```python def color_function(frame, time_fraction, drone_index, formation_index, position, drone_count): return (1.0, 1.0, 1.0, 1.0) ```

Use the Effect Type dropdown list to select Presets or Advanced Presets when you want to drive the light effect with a built-in procedural expression instead of writing Python manually. Presets use the current color ramp as their palette and generate the ramp coordinates automatically for every drone and frame.

The Apply Preset button binds the selected preset to the active light effect. Internally this sets Output X to a built-in custom function, so the effect remains parametric and can still be retimed by changing its start frame, duration, fade in, fade out, storyboard attachment, or spatial constraint.

The preset controls are:

Advanced Presets use the same preset list but default some modes to smoother show-ready behavior, such as pulse blinking and softer reveal fronts. Some presets also have a Hide/Reveal variant that works as a transparency-like overlay on top of the base color, revealing or hiding the underlying color without requiring a black-to-color ramp.

The current preset library includes the following families:

The next group of properties below the color ramp or color image specify the temporal constraints of the light effect, i.e. when the light effect should be applied.

Light effects may also be limited in space such that it affects only a subset of the drones. This is achieved by selecting a mesh in the Mesh picker widget and then setting the Target dropdown to one of the following options (instead of "All drones", which does not create a spatial constraint):

The result of the spatial constraint can also be inverted with the Invert target checkbox. This is mostly useful in conjunction with the Inside the mesh option, allowing you to match only those drones that are outside the associated mesh instead of being inside.

The Output X and Output Y dropdowns determine how the color of a drone is picked from the color ramp or color image. Recall that each light effect essentially produces one or two numbers between 0 and 1 for each drone, and then passes this number through the color ramp or color image to calculate the final color that the effect will apply on the drone. The output dropdowns provide options for picking this number:

Some output mode types (such as Distance from mesh and Gradient-based types) support two mapping modes between the drones and the color ramp:

The Influence parameter sets the overall transparency of the light effect. 1 means that the light effect completely overwrites the base color animation, 0 means no effect at all.

The Randomness parameter can be used to add a bit of randomness to the numbers picked by the drones according to the Output dropdowns. Each drone is associated with a unique random number between -0.5 and 0.5, this number is multiplied by the randomness parameter, wrapping around the edges of the color ramp or image as needed, and the result is added to the number that was calculated based on the setting of the Output dropdowns. This final number is then used to pick the color of the drone from the color ramp or image. Note that the default value of the randomness parameter is zero, which means that the value derived from the Output settings is used as is.

There are several visualization types for pyro effects from which you can choose dynamically:

Particles of the pyro effect are assumed to be hosted by the second material slot in the material list of the drone mesh. The name of the material starts with Pyro of ... by convention, but this is not enforced — you can rename the material, but you need to keep in mind that ButterflyFleet Studio for Blender will always adjust the second material.

Multiple pyro channels are supported by our add-on. Channel indexing starts with 1.

To trigger a pyro event on a given channel, simply set the channel to a convenient value before pressing the Trigger button.

Note that only a single event is supported per channel on each drone, so consecutive triggering on the same channel will overwrite previous events.

Press this button to retrieve pyro payload parameters from the currently selected drone on the current channel.

There are several payload parameters that can be setup for each pyro trigger event. The following payload parameters can be tuned:

When you have setup the pyro channel and all your payload parameters, select the drones you wish to add pyro to and move your timeline to the exact frame when you wish to have your pyro effect appear on the sky. Then simply press the Trigger button to add your pyro event.

Already saved pyro events are stored as a JSON string in the ButterflyFleet-specific "Drone Show" section of each drone’s Object Data Properties. The string can be manually edited as well to allow for easy pyro scripting. Alternatively, you can call Python’s bpy.ops.butterfly.trigger_pyro_on_selection() directly to add additional pyro trigger events to selected drones.

The checkbox at the top left corner of the panel allows you to disable the safety checks entirely, although it is advised not to do so. One valid reason for disabling them temporarily is if you feel that the Blender UI has become sluggish and that the safety checks are responsible for that. The safety checks should have negligible impact on the overall performance of Blender so let us know if you found a situation where disabling the safety checks improved Blender’s responsiveness significantly.

This option lets you define a minimum safety distance between your drones. If there are drones at the given frame that are closer to each other than this safety distance, you get real-time proximity warnings.

By default, the proximity warning is limited to drones above the minimum navigation altitude only (see below in the section about altitude warnings). This is to prevent spurious warnings about drones being too close in the takeoff grid. You can change this in the panel by choosing between the "All drones" and "Drones abouve min altitude" setting.

The text-based proximity warning on the left side of the 3D Viewport editor always shows you the minimum distance between all drone pairs on the current frame. This drone pair is also highlighted with red, along with a red line connecting them.

To enable or disable proximity warnings, use the Show proximity warnings checkbox.

This option lets you define a minimum and a maximum altitude for your drone show. If there are drones above the maximum altitude (measured along the Z axis), or drones moving horizontally below the minimum altitude, you get real-time altitude warnings.

The text-based altitude warning on the left side of the 3D Viewport editor always shows you the overall altitude range of drones on the current frame. Drones above the altitude threshold at a given frame are highlighted in yellow.

To enable or disable altitude warnings, use the Show altitude warnings checkbox.

This option lets you define a maximum horizontal and vertical speed for your drone show (vertical speed can be further differentiated into maximum up and down speed). If there are drones above these velocity limits, you get real-time velocity warnings.

The text-based velocity warning on the left side of the 3D Viewport editor always shows you the maximum horizontal (XY), upwards (U) and downwards (D) velocity of drones on the current frame. Drones above the velocity thresholds at a given frame and drones moving horizontally below the minimum navigation altitude threshold are highlighted in blue.

To enable or disable velocity warnings, use the Show velocity warnings checkbox.

If you need different vertical velocity limits for ascending and descending motion, enable the checkbox next to the Z velocity slider. This reveals a separate Up slider for the upward velocity limit, while the main Z slider controls the downward limit.

This option lets you define a maximum acceleration for drones in your drone show. If there are drones above the acceleration limit, you get real-time acceleration warnings.

The text-based acceleration warning on the left side of the 3D Viewport editor always shows you the maximum acceleration of drones on the current frame, irrespectively of the direction (horizontal or vertical). Note that acceleration is treated as an unsigned quantity: accelerations and decelerations are not distinguished. Drones above the acceleration threshold at a given frame are highlighted in magenta.

To enable or disable acceleration warnings, use the Show acceleration warnings checkbox.

This option lets you define a maximum yaw rate for drones in your drone show. If there are drones above the yaw rate limit, you get real-time yaw rate warnings.

The text-based yaw rate warning on the left side of the 3D Viewport editor always shows you the maximum yaw rate of drones on the current frame, irrespectively of the direction of rotation (CW or CCW). Note that yaw rate is treated as an unsigned quantity: CW and CCW yaw rates are not distinguished. Drones above the yaw rate threshold at a given frame are highlighted in light blue.

To enable or disable yaw rate warnings, use the Show yaw rate warnings checkbox.

Real-time proximity warnings that are running during playback must be fast, therefore we cannot afford finding all pairs of drones in a frame that are closer than the proximity threshold by default; only one such pair will be marked in the 3D view. However, if you see a proximity warning marker and you suspect that there might be more pairs of drones that violate the proximity threshold in the current frame, you can ask for a full, exhaustive scan of all pairs of drones by pressing the Run Full Proximity Check button. This will refresh the current frame and mark all pairs of drones that are too close to each other.

Press the Validate Trajectories button to execute a full validation for a frame range instead of only for a single frame. This might take some time depending on the number of drones and the number of frames selected.

The validation results include the following set of charts:

All the charts will also indicate the thresholds selected in the Safety Check panel so you can quickly decide whether any of the chart lines breach the safety limits.

The ButterflyFleet compiled show format is a single-file descriptor of your complete drone show. It contains the sampled trajectories, light program, yaw, pyro and metadata exported from the Blender project.

If you press the Export ButterflyFleet SKYC button, you have to choose the path and filename of your output file. There are also some parameters you can setup conveniently:

The trajectories and LED light colors of the drones can also be sampled at regular intervals and exported to CSV files for further post-processing in external tools. This option appears only if you have installed and enabled the CSV export addon that is distributed separately. The CSV export will produce a single ZIP file that contains multiple CSV files, one for each drone, with the following columns: time (milliseconds), X, Y and Z coordinates (meters) and the red, green and blue components of the color of the LED light, in the usual 0-255 range, in linear color space.

If you press the Export ButterflyFleet CSV button, you have to choose the path and filename of your output file. There are also some parameters you can setup conveniently:

The Export validation report button creates a unique safety report of your show in .pdf format for standalone self-checking, validated reporting or as a supplement for flight permissions or other administration purposes.

The validation report starts with a summary of flight statistics and safety test results, and continues with detailed plots on all aspects of the implemented safety checks.

If you press the Export validation report button, you have to choose the path and filename of your output file. There are also some parameters you can setup conveniently:

To save some time on final renderings, there is an option to export shows into .skyc and validation report .pdf formats at the same time, in parallel. In this case the sampling of trajectories and light effects - which is generally responsible for most of the export time - is performed only once, not twice, and the export processes are also executed in parallel by the backend.

All properties of this multi-export option are the same as the ones for the individual exporters.

Upon purchasing a professional license, we provide additional exporters to various external drone show formats, including DSS PATH, DSS PATH3, Drotek, EVSKY, HighGreat DAC, LiteBee, etc.

Visit ButterflyFleet Store to purchase a professional license with third-party exporters. Contact us if you need any additional exporters that are not on the list yet.

If you are preparing your drone show as part of a larger event, e.g. with fireworks, use our Finale 3D / FWSim .vviz or Depence .ddsf exporters to export your drone show into formats that can be read by well known visualization softwares:

Note that our exporters that provide compatibility with these software require a professional license that can be purchased from ButterflyFleet Store.

If you press one of the Export to Finale 3D .vviz or Export to Depence .ddsf buttons, you have to choose the path and filename of your output file. The Export selected drones only, Frame range, Trajectory FPS, Light FPS and Export yaw options will be available for these export types as well.

We also provide an exporter to Google Earth .kmz format. This export option lets you validate the spatial requirements of your show in a real 3D terrain context provided by Google Earth.

After defining the render range and FPS of the output, a static .kmz file is created showing all the linearized trajectories of the drones selected for export. The color of the line segments indicate the color of the given drone at that moment.

Blosm for Blender, formerly known as Blender-OSM lets you import Google 3D cities, OpenStreetMap 3D buildings and global real-world terrain into your Blender project with a few clicks.

Murmur is a swarm flocking simulation for Blender and ButterflyFleet Studio, based on the Vásárhelyi et al. 2018 optimized flocking model.

The code for the simulation is prepared by our Discord user @envyofthebirds, representing the company Illuminaero.