Python API
The public names of each module are exported from the module itself:
from vantagekit.core import UpFrame and from vantagekit.kit import ViewerControls.
vantagekit.core
vantagekit core for Kit viewers: frames, smoothing, camera math, bindings and targets.
Standard library only; nothing here imports Kit, so it is tested with plain pytest.
Stage frames
- class vantagekit.core.UpFrame(up='Y', meters_per_unit=1.0, body_forward=None)[source]
The stage’s up axis and units, and a target’s body forward axis.
meters_per_unit is UsdGeom.GetStageMetersPerUnit(stage); all rig tuning is in meters and converted with to_units().
- Parameters:
up (str)
meters_per_unit (float)
body_forward (Sequence[float] | None)
- horizontal(v)[source]
v with its up component removed.
- Parameters:
v (Sequence[float])
- Return type:
Tuple[float, float, float]
- yaw_of(v)[source]
Yaw (radians, from h1 toward h2) of v’s horizontal part; None if v is vertical.
- Parameters:
v (Sequence[float])
- Return type:
float | None
Camera math
- vantagekit.core.orbit_eye(target, yaw, elevation, distance, frame)[source]
Eye at the given yaw and elevation (radians) and distance from target.
- Parameters:
target (Sequence[float])
yaw (float)
elevation (float)
distance (float)
frame (UpFrame)
- Return type:
Tuple[float, float, float]
- vantagekit.core.orbit_from_eye(target, eye, frame)[source]
(yaw, elevation, distance) that put the eye where it is now; the inverse of orbit_eye.
- Parameters:
target (Sequence[float])
eye (Sequence[float])
frame (UpFrame)
- Return type:
Tuple[float, float, float]
- vantagekit.core.chase_view(target, heading, back, up, look_up, look_ahead, frame)[source]
(eye, look point, up vector) behind the target along its horizontal heading.
The camera’s up is the stage up, so the horizon stays level whatever the target’s pitch and roll.
- Parameters:
target (Sequence[float])
heading (float)
back (float)
up (float)
look_up (float)
look_ahead (float)
frame (UpFrame)
- Return type:
Tuple[Tuple[float, float, float], Tuple[float, float, float], Tuple[float, float, float]]
- vantagekit.core.pov_view(target, q, forward, up, right, frame)[source]
(eye, look point, up vector) fixed in the target’s body frame, full attitude.
The body frame at rest is (body_forward, stage up, body_forward x up); the offsets are along those axes.
- Parameters:
target (Sequence[float])
q (Sequence[float])
forward (float)
up (float)
right (float)
frame (UpFrame)
- Return type:
Tuple[Tuple[float, float, float], Tuple[float, float, float], Tuple[float, float, float]]
- vantagekit.core.look_at_matrix(eye, look, up)[source]
Camera-to-world matrix, row-major with the translation in the last row.
The same layout as Gf.Matrix4d().SetLookAt(eye, look, up).GetInverse(): the camera looks along its -Z with +Y up.
- Parameters:
eye (Sequence[float])
look (Sequence[float])
up (Sequence[float])
- Return type:
Tuple[Tuple[float, float, float, float], …]
Smoothing
- class vantagekit.core.Smoothed3(tau)[source]
A 3-vector following its target with time constant tau (seconds); its lag behind a target moving at speed v is v tau whatever the frame times (first-order hold).
- Parameters:
tau (float)
- class vantagekit.core.SmoothedAngle(tau)[source]
An angle (radians) following its target along the shorter way around, with the same first-order hold as Smoothed3 (a steady turn lags by its rate times tau).
- Parameters:
tau (float)
- vantagekit.core.exp_alpha(dt, tau)[source]
Blend fraction for one step of dt seconds toward the target; 1 when tau <= 0.
- Parameters:
dt (float)
tau (float)
- Return type:
float
- vantagekit.core.spring_step(x, v, target, dt, omega)[source]
One exact step of a critically damped spring; returns (x, v).
omega (1/s) sets the stiffness: the spring settles in about 4/omega seconds with no overshoot from rest. Exact for any dt, so it does not depend on frame rate.
- Parameters:
x (float)
v (float)
target (float)
dt (float)
omega (float)
- Return type:
Tuple[float, float]
Bindings
- class vantagekit.core.Binding(action: 'str', input: 'str', kind: 'str' = 'press', mods: 'FrozenSet[str]' = frozenset(), layer: 'str' = 'camera', scale: 'float' = 1.0, deadzone: 'float' = 0.1, label: 'str' = '')[source]
- Parameters:
action (str)
input (str)
kind (str)
mods (FrozenSet[str])
layer (str)
scale (float)
deadzone (float)
label (str)
- action: str
- input: str
- kind: str = 'press'
- mods: FrozenSet[str] = frozenset({})
- layer: str = 'camera'
- scale: float = 1.0
- deadzone: float = 0.1
- label: str = ''
- property device: str
- property name: str
- class vantagekit.core.BindingState(bindings, layers=('camera',))[source]
- Parameters:
bindings (List[Binding])
layers (Sequence[str])
- layer_order: List[str]
- active: Set[str]
- owner(inp)[source]
The highest active layer that binds inp, or None.
- Parameters:
inp (str)
- Return type:
str | None
- key_down(inp, mods=None)[source]
A key or button went down. A repeat (already down) does nothing.
- Parameters:
inp (str)
mods (Iterable[str] | None)
- Return type:
None
- class vantagekit.core.Frame(dt=0.0, pressed=<factory>, held=<factory>, values=<factory>)[source]
What one step saw: fired presses in order, held actions, and axis and delta values.
- Parameters:
dt (float)
pressed (List[str])
held (Set[str])
values (Dict[str, float])
- dt: float = 0.0
- pressed: List[str]
- held: Set[str]
- values: Dict[str, float]
- vantagekit.core.DEFAULT_BINDINGS
Built-in mutable sequence.
If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
Targets
- class vantagekit.core.Pose(position: 'Vec3', orientation: 'Quat' = (1.0, 0.0, 0.0, 0.0))[source]
- Parameters:
position (Tuple[float, float, float])
orientation (Tuple[float, float, float, float])
- position: Tuple[float, float, float]
- orientation: Tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.0)
- class vantagekit.core.CallbackTargets(ids, pose)[source]
A TargetProvider from two callables, for apps that keep poses in their own dicts.
- Parameters:
ids (Callable[[], Sequence[Hashable]])
pose (Callable[[Hashable], Optional[Pose]])
- class vantagekit.core.TargetCycler(provider, selected=None)[source]
The selected target. The selection survives targets coming and going; previous and next step through the provider’s current list.
- Parameters:
provider (TargetProvider)
selected (Hashable)
vantagekit.kit
These adapters import carb, omni and pxr, which exist only inside Omniverse Kit; the
documentation is built without Kit.
Kit adapters for the vantagekit core: camera rig, input router, native navigation handover and Events 2.0 subscriptions. Loaded by Kit as the python module of the lhzn.vantagekit extension.
- class vantagekit.kit.ViewerControls(camera_path, provider, bindings=None, layers=('camera', 'orbit'), settings=None, free_gamepad=None, order=0, consume=False, name='vantagekit', overlay=True, overlay_extra=None)[source]
- Parameters:
camera_path (str)
provider (TargetProvider)
bindings (Iterable[Binding] | None)
layers (Sequence[str])
settings (RigSettings | None)
free_gamepad (bool | None)
order (int)
consume (bool)
name (str)
overlay (bool)
overlay_extra (Callable[[], str] | None)
- on(action, fn)[source]
Handle a press action (replaces a default handler of the same name).
- Parameters:
action (str)
fn (Callable[[], None])
- Return type:
None
- view_badge()[source]
(mode, title, hint) for the current view, e.g. (“orbit”, “ORBIT 101”, “Right stick, drag: orbit …”). The built-in overlay draws it; an app with its own HUD can pass overlay=False and draw this at the top of its panel instead. COLORS in vantagekit.kit.overlay holds the color per mode.
- Return type:
tuple
- class vantagekit.kit.CameraRig(camera_path, targets, settings=None, native=None, usd_context=None, name='vantagekit')[source]
- Parameters:
camera_path (str)
targets (TargetCycler)
settings (RigSettings | None)
native (NativeNavigation | None)
name (str)
- property stage: Usd.Stage | None
- reset_stage()[source]
Call after a stage opens: drops cached ops and returns to free mode.
- Return type:
None
- property attached: bool
- home()[source]
Attached: back to the default chase perspective (behind the target), in chase and in orbit. Free: the saved home view, if any.
- Return type:
None
- orbit_by(d_yaw=0.0, d_elevation=0.0, range_factor=1.0)[source]
- Parameters:
d_yaw (float)
d_elevation (float)
range_factor (float)
- Return type:
None
- update(dt)[source]
Advance one frame; returns True when the camera was written.
- Parameters:
dt (float)
- Return type:
bool
- class vantagekit.kit.RigSettings(views: 'Tuple[str, ...]' = ('chase', 'pov', 'orbit'), body_forward: 'Optional[Sequence[float]]' = None, chase_back_m: 'float' = 12.5, chase_up_m: 'float' = 1.8, chase_look_up_m: 'float' = 1.8, chase_tau_target_s: 'float' = 0.05, chase_tau_heading_s: 'float' = 0.35, pov_forward_m: 'float' = 6.0, pov_up_m: 'float' = 2.5, pov_right_m: 'float' = 0.0, orbit_tau_target_s: 'float' = 0.15, orbit_range_m: 'float' = 40.0, orbit_min_m: 'float' = 2.0, orbit_max_m: 'float' = 20000.0, orbit_elevation_deg: 'float' = 20.0, orbit_min_elevation_deg: 'float' = -10.0, orbit_max_elevation_deg: 'float' = 85.0)[source]
- Parameters:
views (Tuple[str, ...])
body_forward (Sequence[float] | None)
chase_back_m (float)
chase_up_m (float)
chase_look_up_m (float)
chase_tau_target_s (float)
chase_tau_heading_s (float)
pov_forward_m (float)
pov_up_m (float)
pov_right_m (float)
orbit_tau_target_s (float)
orbit_range_m (float)
orbit_min_m (float)
orbit_max_m (float)
orbit_elevation_deg (float)
orbit_min_elevation_deg (float)
orbit_max_elevation_deg (float)
- views: Tuple[str, ...] = ('chase', 'pov', 'orbit')
- body_forward: Sequence[float] | None = None
- chase_back_m: float = 12.5
- chase_up_m: float = 1.8
- chase_look_up_m: float = 1.8
- chase_tau_target_s: float = 0.05
- chase_tau_heading_s: float = 0.35
- pov_forward_m: float = 6.0
- pov_up_m: float = 2.5
- pov_right_m: float = 0.0
- orbit_tau_target_s: float = 0.15
- orbit_range_m: float = 40.0
- orbit_min_m: float = 2.0
- orbit_max_m: float = 20000.0
- orbit_elevation_deg: float = 20.0
- orbit_min_elevation_deg: float = -10.0
- orbit_max_elevation_deg: float = 85.0
- vantagekit.kit.MODES = ('free', 'chase', 'pov', 'orbit')
Built-in immutable sequence.
If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.
If the argument is a tuple, the return value is the same object.
- class vantagekit.kit.InputRouter(state, order=0, consume=False, name='vantagekit')[source]
- Parameters:
state (BindingState)
order (int)
consume (bool)
name (str)
free_gamepad: native gamepad navigation in free mode; None keeps the value found at startup (the app may want it off so the sticks stay with its own controls).
- Parameters:
free_gamepad (bool | None)
native=True gives the camera to Kit (free mode); False gives it to the rig.
- Parameters:
native (bool)
camera_path (str | None)
- Return type:
None
Forget the applied state (a new stage was opened); the next set_native applies.
- Return type:
None
- Parameters:
camera_path (str | None)
- Return type:
None