Troubleshooting and limits#

What to do when something goes wrong, and what Blackbody does not do (yet).

Troubleshooting#

The wrong GPU is used: set BLACKBODY_GPU to part of the GPU's name (for example 3090) and/or BLACKBODY_BACKEND to Vulkan, D3D12 or Metal. blackbody info lists what is available.
The engine does not start: update the graphics driver.
Out of GPU memory: Blackbody fits a scene to the card before it makes its grids, stepping Detail upres and then the voxels down with a notice saying so (see Performance and memory); lower Voxels (longest side), Detail upres or Final resolution yourself to choose what gives way. If it runs out anyway, it frees the GPU, plans within less and carries on (a disk cache keeps its frames and the layout they were simulated at, while frames cached only in memory are simulated again at the smaller layout; if that runs out again, a notice says to close other programs that use the GPU or delete the cache). It plans from the card's size, not from what is free, so close other programs that hold much of the card, or set BLACKBODY_GPU_MEMORY (in GB) to tell it the card has less memory than it reads.
The GPU stopped responding (a driver reset or a time-out, often from one very long frame): Blackbody starts its engine again on a new device and keeps the cached frames; it gives up, asking for a restart, only if that fails three times in a row.
A liquid waits on "Compiling GPU shaders": the liquid renderer's shader is compiled once after an install or an update of Blackbody or of the graphics driver (under a minute; the app starts it in the background when it opens, and a scene that needs it while that runs waits for it). If it happens every time with Vulkan, the driver's own shader cache is being cleared or is full (NVIDIA: Shader Cache Size in the NVIDIA Control Panel). With Direct3D 12 it does happen every time, and takes about 3 minutes: set BLACKBODY_BACKEND=Vulkan if the driver offers Vulkan (blackbody info lists it). BLACKBODY_PRECOMPILE=0 stops the background compile.
Footage will not open: anything FFmpeg decodes should work. Image sequences are found from any one numbered file.
Footage missing after moving a project: Blackbody looks for the clip at its saved path, then at the same place relative to the project, then next to the project file. If none of those has it, File › Import footage relinks it; the fire, camera and track are kept.

Limitations#

Tested on Windows 11 with an NVIDIA RTX 3090 (Vulkan). macOS and Linux use the same code from source, but have not been tested.
Shader compiles: WebGPU offers no pipeline cache Blackbody could keep, so compiled shaders are kept only by the graphics driver, in its own cache (Blackbody keeps a record of what has been compiled, in %LOCALAPPDATA%\Blackbody\shaders on Windows, ~/.cache/blackbody/shaders elsewhere; it says what was compiled, not what the driver still has, so the app compiles the liquid renderer's shader in the background each time it opens, a moment when the driver has it). That shader takes 20 to 55 s cold on an RTX 3090 with NVIDIA's Vulkan driver (earlier versions took 8 to 17 minutes and up to 22 GB of memory). With Direct3D 12 it takes about 3 minutes on the same machine (12 on a busy one), and every time a process starts: the shader translator wgpu uses there (FXC) keeps nothing between runs (earlier versions took over 20 minutes). On Metal and other drivers the time is unmeasured. The background compile runs on the app's own GPU device while the app is open, and the app's GPU work may pause for up to about 0.4 s now and then while it runs; closing the app stops it, and it carries on next time. A process does not see what another compiled after it started (NVIDIA's Vulkan driver), so a render started while blackbody precompile runs compiles the shader itself.
Colour management: sRGB, Rec.709, Linear and ACEScg footage and Standard, AgX filmic, ACES fit and Raw views are built in, and OCIO configs are read for displays, views, looks and colour spaces. The viewer's OCIO view is a LUT (within about 1/255 of the exact transform); renders use OCIO itself.
Camera tracking (Tracking › Track with the ground lined up) follows about 60 spots and works out the camera from them with the lens as lined up, fixed and free of distortion: a zoom, a strongly distorting lens, or a camera that travels with no ground in view needs a solve from a matchmover (.chan or USD). Each frame's camera is found in turn, outward from the lined-up frame, with nothing refining the whole shot together afterwards, so small errors can add up over a long move. With no ground lined up, Track pins the effect to one point in 2D: its position, not rotation, scale or perspective.
.chan import is tested with generated files, not with exports from each package.
The gas is carried by a semi-Lagrangian scheme, which does not keep the total of what it carries exactly: a soft puff of smoke that an object is driven straight through loses about 4% of its amount (12% before the gas an object runs into was pushed out of its way), sharp-edged smoke more. The smoke an object shoves piles up in front of it, up to two to four times as thick, until it flows round. With Detail upres the finer smoke is carried by the air after the object has moved, and loses about a tenth of what the object covers in a step. Cells covered more than about two and a half cells deep in one substep (an object faster than the substeps allow) are still emptied. An object creeping by less than a hundredth of a cell a substep counts as still (so that broken pieces and sand lying still, which jitter a little, are walls to the gas like any still collider): what it creeps over is emptied, and the air it leaves fills partly with the empty air inside it, as before. A burnable collider's burn is laid out in cells a simulation cell across at the size it has when its burn is set up (at the start): growing it a lot makes the burn coarser.
Fire light on the footage, and with the classic lighting engine on the set drawn in CG too, is shadowed along one ray toward the centre of the fire, so a surface lit by two fires far apart gets one shadow (Lume shadows each of the fire's lights on the set it draws). The ground is a flat plane at the fire's base unless a depth pass or a terrain collider describes it. Holdouts are only as good as the colliders, matte or depth pass you give them.
Deep EXR: a thin wisp that only a later anti-aliasing pass catches gets a sample of its own only while the pixel has fewer than its 8 (or 16) samples; after that it joins the nearest one. A pixel's embers are one sample at the nearest ember's depth; one behind nearly opaque flame (as the flat image still shows it) sits at the front of that flame.
GPU memory: what a scene is fitted to the card with leaves out meshes, fabric, grass, matter and Lume (0.4 GB is kept for them), so a scene heavy with those can still run out; the app then starts its engine again within less (but keeps a disk cache's layout, so a scene whose cache needs more than the card has free stops after three tries until other programs let go of the card or the cache is deleted; and a box that grows after that grows only within the cut plan). The plan is a share of the card's memory, not of what is free: other programs holding much of it can still make a scene run out. Each layer of a shot is fitted to the whole plan on its own, though all of them share the card, so a shot of several heavy layers can run out too. A disk cache simulated on a card with more room is fitted again, and so simulated again, on one without room for it (rendering it with --from-cache reads it as it is). The command-line renderer fits scenes to the card too, but stops at a lost device rather than starting again.
A growing box grows but never shrinks during a simulation, and grows only in fire scenes (a fire-and-liquid box keeps its size: the setting is not offered there, and adding liquid to a fire scene turns it off). When the GPU has no room for the old box and the new one at once, a growth goes through the computer's memory (a fraction of a second) instead of being copied on the GPU. VDBs rendered from a disk cache have the simulated air's velocity without the finer grid's swirls, and none if motion blur was off as it was simulated; a sky's have none.
Volumes: a sequence blends between its frames by mixing them (a crossfade), not by moving the smoke along its velocity, so a fast-moving puff between two frames shows as two half-thick ones. A volume is kept at most 512 cells a side and 24 million cells in all (averaged down past that), and no finer than half a simulation cell; a tilted one is resampled on the upright box around it, which keeps to those limits, so it is coarser than the same volume upright. Blosc's Zstd codec needs the zstandard package (or Python 3.14); non-float grids other than vectors are not read. A liquid source from a volume pours from its first frame. USD particles are splatted as soft balls: a cache of more than 4 million points is thinned evenly, and a moving cache's one grid is fitted to 200 of its frames, so a point that strays past them between those frames is cut off at the grid's edge.
Meshes and volumes share one atlas on the GPU, packed in columns within the 2048 cells a side every GPU allows, up to 2 GB. A mesh or volume it has no room for is left out (the others stay), and the viewer and the command line say which: lower Domain › Mesh detail, or use fewer or smaller meshes and volumes.
USD import: a frame offset goes up to 100 000 frames either way. Any distant or dome light after the first is not imported, and a rectangle light's texture is not used. A disc or rectangle light with an IES profile becomes a point light through it (Blackbody's panels take no profile), a portal takes the dome's intensity and colour but not its texture's brightness, and a geometry light is one point light at its geometry's centre, not light from every point of its surface. Still points without velocities become solid balls; points that move or carry velocities become a source.
Fabric: up to 16 fabrics. In water the cloth and the water push each other by the cloth's drag, but the cloth is no wall to the water: water passes through a sheet slowed rather than held back. The water sees it through its drawn layer, so cloth outside the picture is not seen refracted or reflected in the water. Its shadows come from the light volume (half the simulation's resolution): soft close up, and a sheet thinner than a light cell shades a little round its edges. The flames of burning fabric are the fire's own (from the fuel the cloth gives off, at the fire's cell size), not a thin sheet of flame on the cloth itself; ash flakes are drawn a few to each burnt-off point of the cloth and do not land and pile up as ash. Radiation on cloth (the fire's, lava's, hot objects', glowing matter's) is not shadowed: cloth behind cloth, or behind an object, is lit as if nothing were in the way. Drops dripping off wet cloth do not make ripples or splashes in a liquid or wet the ground, the water cloth soaks up is not taken out of the liquid, and cloth in hot water is not warmed by it. Stiff materials at fine detail can need more than the four constraint passes to reach their full stiffness, so they drape slightly softer than measured.
Lights in the set: the smoke's shadow on them comes from the light volume, so it is as soft as a cell of that volume (the beam itself is sharp). How much a light brightens or darkens the footage is judged against the Lighting settings, not measured from the footage. A beam shows only where there is smoke or steam: clear air is clear.
Detail upres adds detail the simulation did not compute: the fine grid follows the simulated air plus noise, so its small swirls are plausible rather than simulated.
Heat expansion makes a fireball shrink as it cools, which is real, but it looks smaller than one tuned with Gas expansion alone.
Tracked air and flame fronts model a room starving and igniting again when air gets in, and a flame front running through gas that is already mixed. The burst of a real backdraft is gentler here: how fast the incoming air mixes with the smoke is modelled as a diffusion, and the smoke's fuel can only burn as fast as air reaches it.
A swirl core narrower than about six cells (a small dust devil) is under-resolved and spreads out instead of forming a column.
Liquids: a light object sitting in a thin film can stick until water seeps under it. Very high viscosity (lava) is approximate: a fixed number of Jacobi sweeps diffuses the velocity less than an exact solve. With a water level, a big wave that reaches the box's side is calmed rather than carrying on; keep the box a little wider than the action. The narrow band carries the deep water on the grid without advecting it, which suits ponds, lakes and wakes, not a deep, fast current. Streams and sheets thinner than about two cells break up early; raise the resolution or keep the box tight. A cell counts as solid when its centre is inside a collider, so where a collider's flat top is just above a cell's centre, the sliver of that cell over it holds water the pressure solve does not see: a stream poured onto it piles up there (and, with heat on, freezes there) until it bursts out. Put such a top on a cell boundary or just under a cell's centre. Surface tension is reliable down to about a centimetre: millimetre drops shed a fine mist and small puddles spread thinner than they should (the contact angle still wets or beads the right way). Two liquids share one index of refraction and one viscosity; a dye differs only in colour and cloudiness. The sea's waves shorter than about twelve cells are drawn on the box's surface rather than simulated. The narrow band keeps the volume as water flows in and out of the deep liquid (a closed box sloshing for ten seconds holds within a few percent), but the deep water keeps its velocity rather than being carried along by the flow, so the sea presets simulate all of the water; keep it off for surf and floods. A surge or bore that runs through the box can show a faint outline at the box's edges from high above. The mirrors past a wave tank's sides repeat the box's water once each way; past that, the open sea. Past the box the sea shoals and breaks over the bed only in the render (the breaking itself is simulated in the box), and the open water's waves travel at the speed for the sea's depth everywhere. Whitecaps and foam are statistical: they do not know about the simulation's own splashes past the box. Where the water shows the ground behind an object standing in it, that ground is the footage on either side of the object carried across it, not what is really there: a pattern or an edge that runs behind the object does not line up, and an object much wider than about 400 pixels on screen still shows itself there. A ray that leaves the water for the backdrop (a reflection, or the scene seen through the water) where a real surface of the depth pass stands shows that surface, whether or not the ray would really meet it. A following box drops what it leaves behind: past it, a wake carries on only as the open water's waves and foam. Hits the footage sees only what the camera sees: what is hidden behind the footage's surfaces is a slab a fixed depth thick. Rain streaks are a fresh set each frame, which reads as rain, not as the same drops falling. Heat and phase changes use water's properties (only the freezing and boiling points can be changed); ice bodies are rigid pieces that do not crack or break apart, and ice pieces touching each other freeze into one; at most 8,192 separate pieces move as solid bodies at once (water frozen into more, such as a spray of frozen drops, has the rest move with the water, the same ones every run, and Notices says so); a steam bubble or a vapour film is smaller than a cell, so film boiling lifts the water by about a cell and the bubbles do not merge into big domes; millimetre drops spread into films rather than beading (the surface-tension limit above), so Leidenfrost drops dancing on a hot pan need very fine cells; steam shows only with fire and liquid in the box. Spray finer than a cell is taken as 2 mm drops only where a cell is mostly air, so water thrown on a coarse grid, which the grid still sees as a sheet, gives off less vapour than the fine spray of a real throw (a smaller box, or finer cells, brings it closer). An object warms and cools with the heat the water takes from it or gives it (unless it Keeps its temperature), with one surface temperature all over.
Weather: precipitation is simulated over the Area; past it only the haze of the fall shows. Snow lies on the topmost surfaces seen from above (the ground and the colliders' tops), not under overhangs. Hail and pellets land on the colliders' own shapes in the liquid's box, and on the surfaces seen from above past it. In a fire-and-liquid box the precipitation is carried by the scene's wind, not by the fire's air. Each falling piece stands for itself: a heavy shower over a big area needs a higher Particle limit. The snow cover is drawn over the shot after the liquid, so the water's reflections show the colliders under it bare: in a snow scene, set Water › Stand-in colour snow-grey, as Snow on a pond does. A scene falls the same way every time it is simulated: new pieces take the free slots in order, each drawn from its number among that step's new pieces (they used to race for slots, and which stones fell changed from run to run). The spray that hail throws up from the water is the exception: it goes into the liquid's spray in the order the GPU's threads reach it, so the order of its drops, and once the spray is full which of them are kept, can differ from run to run.
Repeatability: a scene simulates the same way every time on the same machine, its fire, liquids, fabric, weather, fire with water, lava and falling objects (tests/test_determinism.py simulates each in two processes at once and compares them exactly). Some things can still come out slightly differently from run to run: a liquid whose particles come and go fast, as when lava boils the sea (its random choices, such as which drops boil away, follow the slot each particle happens to be given); and the spray, foam and bubbles over a liquid, hail's splashes among them, which go into a ring in the order the GPU's threads reach it, so their order, and once the ring is full which are kept, can differ (the test compares the liquid's particles, not these). Small differences grow: in turbulent smoke or a splash, a run can look different a few seconds in. Different GPUs and drivers give different results.
Clouds: the air is Boussinesq (incompressible, with its density varying only in buoyancy), which suits clouds up to the tropopause. The microphysics is bulk (each kind of water a single amount per cell, its sizes implied): a single cloud's rain and hail rates are of the right order, not those of a particular storm. A cell is a few hundred metres: clouds smaller than a few cells are drawn with detail added, not simulated, and a cloud's own small eddies are not resolved. The box's open sides take in the background air, so a storm that fills the box goes on being fed; make the box wide enough for the anvil. With no cap, an unstable sounding convects everywhere at once.

Something wrong or missing on this page? Edit it on GitHub.