Recursive AI

Center a replay camera on an entity

OneScope is a free, open-source viewer for simulation recordings, with a desktop window or command-line control, from Recursive AI. MIT or Apache-2.0.

Select an object in the replay, then fit the camera around it with the Frame sel. toolbar button in the desktop window or frameSelection on the command line.

Terminal
dotnet tool install --global RecursiveAI.OneScope.Tool

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

Terminal
onescope open run.oppr --headless \
  --run 'seek {"step":20}' \
  --run 'inspect {"entity":72057598332895233}' \
  --run 'view {"index":0,"frameSelection":true}'

Unzip the example, then dotnet run.

Run the command from the unzipped example. run.oppr is a OnePhysics replay recording of a ball falling toward a static ground box; you can record your own replay from a OnePhysics simulation.

72057598332895233 is the ball’s entity ID in run.oppr. For your own replay, list entities to find the ID, then select it with inspect. OneScope needs a working graphics renderer even without a window.

The last JSON result shows the 2D camera’s new target:

Text
"target":[0,3.4481876,0]

The full program

The bundled run.oppr replay was recorded with OnePhysics 1.0.0. The ball has radius 0.5 m and starts at (0, 4); the ground is 20 × 1 m and centered at (0, −1). The program installs OneScope.Tool 1.0.0 and prints the camera target at tick 20 before and after framing the ball. It then enables tracking and seeks to tick 30.

C#
using System.Diagnostics;
using System.Text.Json;
 
// Install the published command-line tool into the build folder.
string toolDir = Path.GetFullPath("obj/onescope-tool");
string tool = Path.Combine(toolDir,
    OperatingSystem.IsWindows() ? "onescope.exe" : "onescope");
if (!File.Exists(tool))
    Run("dotnet", "tool", "install", "RecursiveAI.OneScope.Tool",
        "--version", "1.0.0", "--tool-path", toolDir);
 
var results = Open(
    "seek {\"step\":20}",
    "view",
    "inspect {\"entity\":72057598332895233}",
    "view {\"index\":0,\"frameSelection\":true}",
    "track {\"view\":0,\"on\":true}",
    "seek {\"step\":30}",
    "view");
// results[2]: view before framing; results[4]: view with frameSelection.
// results[7]: view after tracking is enabled and the replay seeks to step 30.
PrintTarget("Before framing", results[2]);
PrintTarget("After framing", results[4]);
PrintTarget("Tracking at step 30", results[7]);
 
static void PrintTarget(string label, JsonElement result) =>
    Console.WriteLine($"{label}: {result.GetProperty("views")[0].GetProperty("target")}");
 
JsonElement[] Open(params string[] operations)
{
    var arguments = new List<string>
    {
        "open", "run.oppr", "--headless", "--size", "640x480"
    };
    foreach (string operation in operations)
        arguments.AddRange(["--run", operation]);
    string output = Run(tool, arguments.ToArray());
    return output.Split('\n', StringSplitOptions.RemoveEmptyEntries)
        .Select(line => JsonDocument.Parse(line).RootElement.Clone())
        .ToArray();
}
 
string Run(string command, params string[] arguments)
{
    var start = new ProcessStartInfo(command)
    {
        RedirectStandardOutput = true,
        RedirectStandardError = true
    };
    foreach (string argument in arguments) start.ArgumentList.Add(argument);
    using var process = Process.Start(start)!;
    var output = process.StandardOutput.ReadToEndAsync();
    var errors = process.StandardError.ReadToEndAsync();
    process.WaitForExit();
    if (process.ExitCode != 0)
        throw new InvalidOperationException(output.Result + errors.Result);
    return output.Result;
}
Text
Before framing: [0,-1,0]
After framing: [0,3.4481876,0]
Tracking at step 30: [0,2.763532,0]

If the view draws nothing for the selected entity, Frame sel. falls back to ordinary Frame instead of fitting that entity.

Variations

Track the ball while scrubbing

Append these operations to the onescope open command:

Terminal
  --run 'track {"view":0,"on":true}' \
  --run 'seek {"step":30}' \
  --run view

View 0 now reports "target":[0,2.763532,0] and keeps the framing zoom ("halfHeight":0.56).


The short answer

In the OneScope window, scrub to the tick you want, select the object in the entity list, and click Frame sel. in the toolbar. From the command line, inspect selects the entity, then view with frameSelection: true fits the specified camera. This adjusts a view you already have; it doesn’t add a camera or move time.

How do I center a replay camera on a selected object?

Seek before framing so the camera fits the object’s drawn bounds at the tick you’re investigating. In the example, view 0 is the 2D camera. Its target is the center in world coordinates, and halfHeight is its vertical half-extent. Changing the frame can move the target and change the zoom at once. The entity ID in the snippet belongs to the ball in this file; use your replay’s entity list to identify the object in another recording.

Frame and Frame sel. are different commands. The former fits the moving bodies by default, leaving out static bodies, sensors and drawings not associated with an entity when there are other items to fit. The latter fits the bounds for the selected entity. If framing looks like it ignored your selection, check that the view shows the right replay and that the replay module draws the entity at that tick with the current overlays. An inspector entry alone doesn’t give the camera a shape to fit. See the framing rules.

How do I make the replay camera follow a moving object?

Framing is a one-time fit. If you frame an object and then seek, the camera does not keep re-fitting to it. Turn track on for the view to re-center on the selected object at each seek. The variation shows the target moving down as the ball falls, while the 2D zoom stays the same. Use framing alone when you want to see how an object moves relative to a fixed part of the scene.

Tracking and framing apply to an individual view. You can leave the other camera on a wide shot to keep your bearings, while a single view follows the object. You don’t need to create or arrange multiple views just to center the one you already use.

All onescope recipes