Report the camera, its axes and ranges, and whether it is a real device.

Call this first. It says which camera was found, the range each axis accepts, where the camera believes it is pointing (a hint, not proof), what has been calibrated, and -- if no real device was found -- the reason. simulated: true in any result means nothing physical moved and no picture was ever taken.

Point one axis at an absolute value, and return what the picture confirms.

axis is one of pan, tilt, roll, zoom. Gimbal axes are in degrees; zoom is the device's own ratio x100, so 300 means 3x. The value is clamped to the range the camera advertises and the clamped value is what gets sent.

This moves the camera and waits for it: allow roughly a second for a gimbal axis and three for a zoom. moved is decided by comparing frames, never by the device's report -- the report is returned as device_reported and labelled a hint, because this hardware was measured claiming positions it had not reached. If the picture shows no change and the camera was not already at the target, the call fails rather than reporting success.

Move one axis relative to where the device says it is now.

Relative moves inherit the device's reported position, which is a hint: after a series of nudges the accumulated position may drift from belief. The picture check still tells you whether this call moved the camera; it cannot tell you it is at an absolute angle.

Move an axis smoothly to a value over a chosen duration.

Use this for any move that should read as deliberate: a slow pan across a scene, a gradual push in. The axis is driven by streaming absolute targets at 15 Hz rather than one jump, which is how this hardware was measured moving smoothly. ease is one of linear, in_out, out, in; in_out starts and stops gently, which is what makes a move look intentional. Long sweeps take as long as seconds, so expect to wait.

Set optical zoom as a multiplier: 1.0 is wide, up to the camera's maximum.

Convenience over the raw zoom axis, which counts in hundredths. The requested ratio is clamped to what the camera supports and the clamped value is returned.

Return every axis to the camera's own default: centre, level, unzoomed.

Capture one frame of what the camera currently sees, as a PNG image.

This observes the camera's view. Call it when the user asks to see the picture, not on your own initiative, and be aware that a still only tells you what is in front of the lens -- not where the camera is, and not whether a move happened.

Remember the current direction under a name, for later use.

Pan is an absolute axis whose meaning depends on where the camera is standing, so "point at the door" is unanswerable without recording it once. Call this with the camera already pointed where you want, and the label becomes usable with go_to.

List the directions recorded for this camera, and its calibrated default pose.

Point the camera at a direction recorded earlier with aim_learn.

Each axis is moved and confirmed from the picture, the same as aim. A label is resolved to the angles recorded for it, which may drift if the camera has been physically moved since; the picture check still proves that each axis moved, not that the label is right.

Execute a multi-step camera move, verifying after every waypoint.

Each step is an object: {"axis": "pan", "to": 60, "seconds": 2.5, "ease": "in_out"}. Steps run in sequence and every axis that moves in a step is written on each tick, so a step naming two axes produces a genuine diagonal rather than a staircase. Add {"hold": 1.0} to pause after a step.

The whole plan is validated against the camera's advertised ranges before anything moves, so an impossible shot fails without touching the hardware. Afterwards the report gives the picture difference at each waypoint, which is how you tell a shot that happened from one that did not. A long shot takes its full duration; do not set a host timeout shorter.

Store the current picture under a label, so it can be compared later.

Useful before a move whose result you will judge later, or to establish what "the wide shot" looks like. Marks live in memory for this session only.

Compare the current picture with one stored by mark_view.

Answers "is the camera still looking at what it was looking at?", which is the question a scene change can otherwise hide: a person walking through the shot changes the picture as much as a pan does, so treat a small difference as "still there" and a large one as "worth looking at".