Blackbody simulates fire as a real gas: fuel burns into heat, soot and flame, hot gas rises, swirls and expands, and smoke drifts. Flame colour and brightness come from blackbody radiation, so thick flame saturates the way real flame does. It simulates liquids too, from a pour to an ocean, and lava, ice and steam, cloth that burns, objects that fall and break, bullets through glass, wood and steel, ropes and hinges, explosions, lightning, sand, snow and mud, and the weather, up to clouds that build into storms. You can put any of them together in one scene, and they push on each other.
You place the effect in your shot: line up the ground in the footage, track the camera move, line up the walls and steps it should meet, and it stands in the shot at its real size. Then render any of these:
| Output | For |
|---|
| A finished composite (ProRes, H.264, H.265, DNxHR) | delivery and review |
| An element with alpha (ProRes 4444, PNG) | any editor |
| Multi-layer and deep OpenEXR, and the composite as an EXR sequence (with Lume's light passes) | Nuke, After Effects, Fusion, Resolve, Flame |
| OpenVDB volumes, and USD or OBJ meshes | Blender, Houdini, Maya, Cinema 4D, Unreal |
New since 1.0 (see the changelog): things that fall, break and hang on ropes and hinges · ramps, wheels and motors · explosions · lightning · sand, snow, mud, jelly and clay · guns and bullets · fifteen woods that bend, split and burn as wood does · objects with heat · path-traced Lume lighting · burning text and logos · Build and Shot workspaces with a 3D gizmo and right-click actions · lining up the ground and tracking moving cameras · surfaces · layers and roto · search everything (Ctrl+K) · your own blocks · repeat in a row or a ring.
Contents
A tour
Fire and smoke
Each fire is measured against real ones: its flame height, its gas speed, and the rate at which a fire of its size puffs. Fire can spread over the ground and burnable objects, start spot fires from blown embers, and flash back through spilled vapour. A closed room runs out of air, and a hose puts the fire out into steam. Metal salts colour the flames, and sparks fly with full gravity and bounce off the ground. The fire guide
Fabric
Curtains, flags and towels are made from real fabrics with their measured weight, stretch and stiffness. They blow in the fire's own air and catch at their ignition temperature. They then burn the way cloth does: toasting, a glowing line, char, and holes that spread. Wet cloth holds at 100 °C and steams until it dries, and a sheet drawn through water drags the water along with it. The fabric guide
Cloth holds what lands on it, and tears when it cannot. Things that fall come to rest in it: a crate dropped onto a sheet laced into a frame sinks in and stays there, the sheet sagging under it. Sand poured onto a sheet tied to four posts heaps in the dip it makes, and not a grain gets through. With Tears on, cloth rips where its threads are pulled past their breaking stretch, as each fabric really does (canvas and nylon ripstop hold out longest, chiffon and linen give soonest). A steel ball dropped beside the crate stretches the sheet into a cone and tears a ragged hole; the crate goes in after it and the torn flaps hang down. The rip runs on from where it starts as a slit, a thread at a time, the way a snag in a sheet does. Fabric can hang from its top edge, one side or its corners, or be held all round its edges, like a trampoline. Tearing · Things that fall on it
Things that fall, break and swing
Any object can fall: it tumbles, slides, bounces, stacks and knocks things over, in real materials (wood, stone, brick, steel, glass, rubber and more), and the smoke, the water and the wind push it about. Burning ones keep burning as they tumble, and lights or flames attached to them go along. The guide
Breakable wood burns as wood does, spot by spot over its surface: it catches where enough heat reaches it (about five seconds in the flames for pine, never below 12 kW a square metre), fire climbs it fast and creeps over it slowly, it chars at its real charring rate, black and cracked into blocks that glow in their cracks, and it chars through its whole thickness, its glue weakening with what is left of it. So char starts where the flames touch it and spreads from there, rather than a whole board darkening at once. Real wood takes tens of minutes to burn down, so Spreading fire › Burn speed-up time-lapses its burning while the flames and smoke move at their own speed: Shed on fire flashes over, burns all over and falls in, its burnt pieces crumbling to ash. Breaking and burning
Things break where and as hard as they are hit. A piece breaks away when something meets it faster than its material takes (glass and pottery about 2.5 m/s, brick 2, wood 7, steel 60), and the cracks crowd round where it is struck: small chips there, larger pieces further off. A crack runs on as far as the material lets it: a stone thrown through a window leaves daggers of glass in the frame, a vase stays whole until it shatters on the tiles into curved shards, in a puff of dust, and a brick wall comes apart at the mortar. Metal and plastic bend and stay bent: a post hit by a wrecking ball folds over. Breaking
Objects hang on ropes, steel cables, chains, springs, hinges and ball joints, from a fixed point or from another object: a wrecking ball on a crane, a door on its hinges, a lamp swaying on its flex, a seesaw. Ropes go slack and are caught with a jolt, they snap past their strength, and a rope thrown over a beam or a post goes round it: a crate hangs from it and swings under it. A chain is steel links, as heavy as a real one (12 mm: about 3 kg a metre), hanging in its own curve, catching on what it meets and piling up where it lands. Joints and ropes
People and cars are objects built of parts on joints. A person is a crash-test figure, 1.8 m and about 80 kg, its limbs turning only as a body's can (a knee bends only back). It stands braced until something hits it faster than 1.5 m/s, then goes limp and falls as a body does, over a car's bonnet or off a ledge. A car is 4.4 m and about 1300 kg on four sprung tyres: drive it, keyframe its speed and steering, and it drives over grass leaving its tracks flattened, knocks walls down and carries a person on its bonnet. Without footage, everything is drawn in CG on a stage, a floor out to the horizon lit by the fire. In your footage it goes in with its shadows on the real ground. People and cars
Nearly all of the frame can be path traced with Lume (left: the classic engine, right: Lume): the set drawn in CG, the smoke and steam, the cloth and the grass, clouds, and water in a liquid scene without footage, cloth or grass, refracting what is under it and throwing its caustics on the floor (the flames are drawn as before, in its light, and the sea's waves, lava, ice and any other water by the liquid's own renderer, over the set Lume lit). Light bounces from surface to surface, so a fire inside a shed lights its walls and the light they throw back fills it, and smoke is lit as it really is, by the flames, the sun and the sky scattered through it (the classic engine over-lights thick smoke two to five times, so presets made with it give smoke a dark colour: with Lume set Shading › Smoke colour to what the smoke really is, pale for wood and grass, near black for oil and rubber). Each fire light, glowing patch of hot metal and lamp casts its own shadow, as soft as the light is big, through the objects and the smoke. An HDRI's sun, or a physical sky's (its blue, its haze, its reddening at sunset), casts sharp shadows, and glass, ice and jelly bend and tint what is seen through them and focus the light into caustics. Measured against a research path tracer on ten test scenes, its mean brightness is within 0.1% on every one, and after the same time it has less error than that tracer's best sampler for each scene on nine of them (on the simplest, a furnace test that renders in a few milliseconds, 1.2 times as much). Lume lighting
Lume splits the set's light into passes for the comp (the key light, the sky, the fire and the lamps, each a layer of the EXR to turn up, down or recolour), bends each colour by its own index through glass, ice and water (Dispersion: the rainbow fringe round a caustic, the fire of a gem), focuses the fire's own flickering light through glass, can light the CG set by the footage itself, and traces the light a cloud scatters hundreds of times: measured against Mitsuba path tracing the same cumulus, it is within 3%, where the classic estimate is about 40% too dark. In a liquid scene without footage, cloth or grass, Lume traces the water as it is: it reflects and refracts by the exact Fresnel terms, rippled as it moves, takes on its own colour over the way through and clouds with its murk or dye, and the floor under it takes its caustics in the water's colour. Light passes · Clouds
Any object can be tilted and rolled as well as turned, so a plank becomes a ramp, a wall leans and a wheel stands on its rim; things slide down a slope steeper than their friction angle and stay put on a gentler one. A hinge can have a motor: four wheels hinged to a cart drive it along, a turntable spins up until what is on it flies off, a windmill's sails stir the smoke. Tilted objects · Motors
Bullets and wood
A shot is a gun firing real cartridges, from an air-rifle pellet to a .50 BMG, each bullet flying its real path and doing what a real one does: it goes through glass, wood and car doors and on, slower; flattens on steel in a splash of lead and sparks; chips a crater out of concrete or brick in a puff of dust; skips off water, concrete and steel when it comes in flat; opens a cavity in water that swells and collapses; throws sand and snow up out of a crater; punches holes in cloth; and knocks over, spins and shatters what it hits. What it leaves stays on what it hit, its holes and craters carved right into it: splinters standing out round the split in the back of a board, a crater of flat facets in concrete or brick, a hole in glass ringed with frosted crushed glass and a web of cracks, a grey star of lead on steel. Put one in from Create › Guns & bullets, aim it, and set its cartridge, rounds and rate of fire; key its muzzle and its aim to sweep it across a scene. Presets: Shooting range, Bullet through glass, Bottles on a fence, Steel gong, Machine gun at dusk. Bullets
Wood is fifteen woods, from balsa to oak and teak, plywood and MDF among them, each with its density, its stiffness along the grain and its strength along and across it from the USDA Wood Handbook, and its look drawn solid through it: rings, knots, pores and rays, heartwood, so a cut, a break or a bullet's hole shows the same wood inside. It bends before it breaks (a 2 m pine plank sags about 2.5 cm under 10 kg, as beam theory says) and is as strong as a sawn board is rated; bent too far it snaps in a jagged greenstick break, splinters standing out of both halves. An edge driven into its end grain splits it along the grain, as an axe does (a 3 kg wedge at 8 m/s splits a 24 cm round of pine in two), a log breaks into wedges along its rays, a bullet holes it with a split torn out of its back, and it burns as wood does. Presets: Breaking a board, Bullets through boards, Woods. Wood
Explosions and lightning
A source's Blast is an explosive charge, in kilograms of TNT. When it goes off, its blast wave throws the things that fall, blows breakable things apart piece by piece and scatters sand and snow, by the impulse a blast that size gives at that distance, while the fireball and smoke column rise. Lightning is a light: a bolt from where it starts to where it strikes, jagged at every scale, with branches in its first flash. It flashes a few times down the same channel, lights the set and the smoke through each flash, and sets fire to what it hits. Explosions · Lightning
Sand, snow and mud
Sand pours and piles at its angle of repose, wet sand holds a cut edge, mud slumps and flows until it is thin enough to stop, jelly wobbles and springs back, and clay squashes and stays squashed. Each is hundreds of thousands of particles that remember how they have been squeezed (the material point method, on the GPU). Things that fall land on it or sink into it, objects plough through it, and cloth catches it (a sheet held at its corners sags under the sand poured onto it) or drapes over it. Water gets into sand and carries it off: a pour digs a gully down a heap, and a sand castle the water reaches soaks through and slumps. A body of it can fill a closed mesh of your own (OBJ, STL or a USD prim): a chocolate bunny, a sand sculpture, jelly turned out of a mould. Chocolate letters are any words in any font, in chocolate that melts in a hot pan or by a fire. The guide
Snow, mud, clay and wet sand stick to what they touch, each as hard as it really does: a snowball of packing snow thrown at a brick wall squashes where it hits and stays there, powder snow slides off, mud clings to a crate dragged through it, and dry sand does not stick at all. Heat passes where things touch, as fast as the two materials pass it on: squares of chocolate in a 180 °C steel pan melt from the bottom, slump into glossy pools and run together, more slowly on a wooden board as hot, and snow melts from below where it lies on anything warmer than freezing, as well as wherever flames touch it. Wax, chocolate and metal melt in the fire too and set again as they cool, and molten iron glows and lights the floor round it. Dry leaves, sawdust and coal catch fire, feed it, and burn down to ash. Things that melt
Wind blows dry sand, fresh snow, leaves, sawdust and ash off a heap once it passes the speed that starts their grains moving, and carries as much as a wind that strong really carries: the heap's windward side wears down and its crest creeps downwind, and dusty stuff throws dust into the smoke. What moves it
Grass and plants
Lawns, long grass, wheat and reeds, every blade simulated: they bend in the wind in rolling waves and lean into a fire's draught, slow the wind blowing through them, part round what moves through them and spring back, and grow on the ground or up a hillside. A dry field lit at one edge carries the fire across by itself, faster downwind, feeding the flames and leaving black stubble. The guide
Text and logos
Type words in any installed font and they become solid 3D letters: Burning text has fire all over them, Text is a solid object to set on fire, drop or smash, and Water letters fall and splash. Burning logo, Logo or picture and Water shape trace an SVG, PNG or JPG the same way. Change the words, font or size later from the right-click menu. Words on fire
Water
FLIP particles on the GPU produce splashes, sheets, drops, spray, foam and bubbles. The surface is ray traced as a real dielectric, so your footage refracts through it and reflects in it. Floating objects behave as rigid bodies, and viscosity ranges from olive oil to honey. Dyes, two liquids that don't mix, rain, caustics and an underwater camera are all built in. The liquids guide
The sea
A real ocean spectrum of waves runs on to the horizon. Whitecaps and foam streaks match the wind. Surf spills, plunges and throws a barrel over a reef, and there are tsunamis, tidal bores, tides and rivers. The sea guide
Lava, and fire with water
Lava glows as a blackbody, crusts over as it cools and lights everything around it. Fire, water and lava can share one box: water soaks the fuel and boils off in a plume of steam, and lava boils the sea while its skin chills black. The lava guide
Things dropped on lava float or sink by its density (2600 kg/m³: a log rides high and is carried along by the flow, while steel is swallowed and shoved along). It flows round broken pieces and sand, snow and mud, heats what it touches and radiates its heat, scorching cloth hung near it. Preset: Log on a lava flow. Fire, water and lava together
Ice, boiling and steam
Liquids carry a temperature, with water's real heat capacities and latent heats. Water freezes into ice that floats a tenth out of the water, boils in streams of bubbles, skates on its own vapour on a hot plate, and evaporates into steam. The ice and steam guide
Objects have heat too, warming and cooling by what they are made of and how big they are: a steel bar in a fire heats through and glows, lighting what is round it, a log's skin scorches while its heart stays cold, and a red-hot steel ball dropped in water boils it, held off by a film of its own steam at first, and cools to black. Heat
Weather and clouds
Snow, sleet, freezing rain, graupel and hail fall as the column of air above decides. Each piece melts and refreezes on the way down and settles where it lands. Clouds build from the sun-warmed ground into storms that rain and hail. The weather guide
Build anything
Blackbody opens in Build: an empty stage with a camera of your own. Put in one thing from the card on the stage, or anything from Create (Ctrl+N), which has more than 100 building blocks: fires, smoke, steam and sparks, liquids, fabric, weather, forces, objects, things that fall, ropes and hinges, guns and bullets, sand, snow and mud, lights, text and logos, and the blocks you saved yourself. What you put in decides what the scene simulates, and fire, water, cloth, rigid bodies and sand all simulate together.
- Move it with the gizmo. Arrows move the selected thing along X, Y and Z, squares stretch it, the ring turns it and its middle slides it over the ground. Ctrl snaps. Drag a block from Create into the viewer to put it where you drop it.
- Right-click it for what it can do. Set it on fire. Make it fall, or drop it at this frame. Make it breakable, and choose what it breaks into. Hang it on a rope, put it on a spring, hinge it or tie it to another object. Make it float, sink, hot or freezing, hollow it out. Soak a cloth or let it go. Pour sand from it, or change what it is made of. Turn a source into fire, smoke, steam, water, lava or a force. Attach it to something so it follows it, or send it along a path you click out on the ground.
- Forces: a fan, an updraft, suction, a vortex and wind push the air, and with it the smoke, flames, embers and cloth.
- Search everything (Ctrl+K). Type what you want: an action on the selection (make it fall, set it on fire), a building block, a menu command, a setting or an effect, and press Enter.
- Several things at once. Ctrl+click, Shift+drag a box or Ctrl+A to select several, and they move and turn together. Group them, or Repeat them in a row, a ring or scattered, with what is attached to them coming along.
- Your own blocks. Save as a block keeps what you built, with its meshes and what is attached to it, under Yours in Create, as one
.bbblock file you can share.
- The shot's camera from your view. In Build, Use this view gives the shot the view you have and Key here keys it at this frame (keys at two frames make a camera move); with footage, the camera matches the footage instead. The shot's camera
- Animate it. Click the ◆ next to a setting to keyframe it. The animation editor lists every animated setting with its keys, and the timeline shows each source's start and stop, each cloth's let-go time and each pour as bars you drag.
- Layers and roto. Layers put several effects in one shot, such as a campfire in front and a waterfall behind, each its own simulation, composited back to front. Roto shapes drawn round what is in front of the effect, and keyed over the shot, put the effect behind them.
- Start from an effect. The Effects tab has 114 presets, from a candle to a thunderstorm, sorted into fire, liquids, fabric, the sea, smoke, blasts, ice, weather, falling and breaking, sand, snow and mud, and bullets and wood. Click one and it simulates live.
Build your own has every block and action.
Into your footage
Stock elements never match your camera, your light or your lens. Blackbody puts the simulation inside your shot.
- Line up the ground. Drag a grid's four corners onto anything rectangular lying on the ground in the footage: a paving slab, a rug, a parking bay. The lens comes from the vanishing points and the camera's tilt, roll and height from the rectangle (or from what the file says about the lens, for photos and phone video), and a perspective grid, the horizon and a 1.75 m figure are drawn over the footage to check it. The effect then stands on the real ground at its real size. No rectangle in view? Line up from the horizon. Sloping ground? Add two upright lines and the world stays level.
- Track the camera (Ctrl+T). About 60 spots are followed through the footage to a fraction of a pixel, spots that move by themselves are dropped, and the camera's turn and travel are worked out on every frame, in metres: a pan, a dolly, a walk, a car or a drone. The effect stays put on the ground.
- Line up surfaces. A wall, a table, a step, a ramp or a flight of stairs in the footage becomes a solid where it is: water splashes off it and runs down it, smoke flows round it, fire spreads over it, and it hides the effect behind it. Blocks dropped onto the footage land on table tops, steps and slopes.
- It goes behind real things using stand-in colliders, roto mattes or the footage's depth pass, and it lights the scene: the fire lights the ground and walls in the footage, shadowed by its own smoke. With Lighting › Environment from the footage the shot lights what you build too, wrapped round the set as a panorama, so with Lume a CG object takes its colours from each side and reflects them (the classic engine takes their average).
- It looks like your camera shot it: the lens's blur and distortion, heat haze, highlight roll-off, and the footage's own noise.
- Lights like the real ones. Point, spot and area lights (a lit window, a softbox, an LED panel: Lume traces the panel itself), a real fixture's Light profile (IES) throwing its own pattern, brightness in lux or in lumens as on the box. They light the smoke and the set, and under a real light in the footage the ground darkens where the smoke drifts in front of it. Lights in the set
- What you build goes in too. An object's Look is CG, In the footage or Automatic (CG without footage, and in a shot only for things that fall or float): a CG crate goes over the footage lit by the shot's light, its shadow darkening the real ground, hidden behind real things by the depth pass and matte. CG objects in your footage
A camera solve from your matchmover (.chan), or a whole USD scene with its camera, objects and lights, comes in too. Fitting it into your footage · Moving shots and scene import
Emission, heat, depth, alpha, fire light and the beauty, from one render. See Outputs.
Get started
You need Python 3.12 or 3.13 and a GPU with Vulkan, Direct3D 12 or Metal (most cards from the last eight years).
git clone https://github.com/gjnail/blackbody.git
cd blackbody
Then double-click Blackbody.bat on Windows, or run ./blackbody.sh on macOS or Linux. The first run creates a private Python environment and installs the dependencies (about 400 MB), USD and OpenColorIO among them; if that fails or is interrupted, the next run tries again. Install and first steps has the details, including how to build a standalone Windows app.
Build something: put a thing in from the card on the empty stage or from Create, move it with the gizmo, right-click it to make it do something, press Space to play. Or put an effect in your footage:
- Import your footage (Ctrl+I). Video, image sequences and stills all work, and the Shot workspace shows it.
- Line up the ground (Ctrl+Shift+L) and, if the camera moves, track it (Ctrl+T). A card in Shot walks you through the steps.
- Pick an effect in Effects, or drop a building block onto the footage where you want it.
- Match it in Composite: exposure, heat haze, light on the footage, glow and grain.
- Render (Ctrl+M) any combination of outputs in one pass.
The tutorial takes a shot from footage to final render in about 30 minutes.
Documentation
| Guide | What is in it |
|---|
| Install and first steps | Requirements, install, the window, building anything, putting an effect in your shot, text and logos, layers, animation |
| Tutorial: your first shot | Footage, placing, matching, tracking, keyframes, rendering |
| Presets | All 114 built-in effects |
| Fire, smoke and sparks | Puffing, swirl, sparks, colour, steam, spreading fire, rooms, flame fronts, meshes |
| Fabric and burning cloth | Real fabrics, burning through, soaking, dripping and steaming |
| Things that fall | Rigid bodies, materials, breaking, ropes, springs and hinges, explosions, lightning, tilted objects, motors, the CG stage, CG objects in footage |
| Sand, snow and mud | Sand, wet sand, snow, mud, jelly and clay: bodies and pours, what moves them, how they look |
| Grass and plants | Lawns, long grass, wheat and reeds: what moves them, fire running through them, how they look |
| Bullets | Guns and cartridges, and what bullets do to glass, wood, steel, concrete, water and gel |
| Wood |
The same guides, with full-quality video, are on the website.
Command line
blackbody render shot.bbfire -o renders/fire.####.exr
blackbody render --preset campfire --footage plate.mov -o comp.mp4 --content composite
blackbody simulate shot.bbfire --cache //server/cache/shot
blackbody render shot.bbfire --from-cache //server/cache/shot --frames 1001-1050 -o fire.####.exr
From source, blackbody is python -m blackbody. See Command line and render farms.
How it works
Fire is an incompressible, buoyant, reacting gas on a staggered grid, solved with MacCormack advection and a geometric multigrid pressure solve. Liquids are FLIP/APIC particles with a free-surface pressure solve. Sand, snow, mud, jelly and clay are MLS-MPM particles with elastoplastic materials. Cloth uses XPBD with multigrid bending, and tears. Rigid bodies, joints and breaking run in MuJoCo, coupled both ways to the gas, the liquid, the matter and the cloth. The sea is an FFT ocean spectrum, and the sky is a Boussinesq atmosphere with bulk cloud microphysics. Volumes are ray-marched with Planck emission and multiple scattering, liquids are ray traced as dielectrics, and objects, pieces and grains are drawn on a CG stage with soft shadows, or lit by Lume, a path tracer. It all runs in WGSL compute shaders through wgpu, driven from Python and a Qt (PySide6) app. How it works has the details.
More than 300 tests check the physics against textbook values and measurements, such as flame heights, plume speeds, wave spectra, whitecap cover, boiling rates, fall speeds, angles of repose and blast impulses:
pip install pytest
pytest -q
Contributing
Bug reports, footage that breaks it, physics checks and pull requests are welcome. CONTRIBUTING.md has the rules for changes to the simulation, how to build and test, and the source layout. The guides live in docs/ as Markdown, and the website is built from them, so a change to a feature and to its guide can go in the same pull request. Questions and finished shots go in Discussions.
Please report anything that could make Blackbody run code from a file, or write or delete files it shouldn't, privately. SECURITY.md says how. Participation is covered by the Code of Conduct.
Support
Blackbody is free. If it saved you a shot and you'd like to say thanks, you can
buy me a coffee on Ko-fi.
License
MIT. The Barlow font used on the website is under the SIL Open Font License. The lava-field photograph in tools/plates is a public-domain USGS photo (see tools/plates/SOURCES.txt).
