UVC PTZ Camera

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.

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.

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.

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".

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.

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.

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.

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.

Compile a shot and report what it would do, without moving the camera. Takes exactly the step list `run_shot` takes: each step is an object like {"axis": "pan", "to": 60, "seconds": 2.5, "ease": "in_out"}, optionally with {"hold": 1.0} to pause after it. Every step is validated against the camera's advertised ranges and clamped exactly as it would be at execution time, so an impossible or out-of-range shot is refused here, before anything moves. Use this to compose a shot. It returns the per-step schedule (where each axis starts, the value it was clamped to, how far it travels, how many ticks it costs), the per-axis envelope, the total duration, and the axes with their ranges so the next attempt can be written against the real limits. Nothing is written to the camera and no frame is captured, so it is safe to call as often as you like while deciding. The `from` values come from the device's own position report, which this server treats as a hint rather than a fact. `run_shot` recompiles from the same hint when it runs, so a plan and its execution agree unless the camera moved in between.

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

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.

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.

Start following a subject, closing the loop on the picture. While this runs the server keeps capturing frames and moving the camera to hold the subject near the centre of the frame: detect, measure the offset, take a bounded step, look again. It decides only from the picture, because this class of camera's position report cannot be trusted -- and it reports the residual offset every iteration, so a loop that is losing the subject looks like one instead of seeming to work. It looks at whatever the camera sees for as long as it runs, which may be a room with people in it. Start it when the user wants the camera following something, and stop it when they do not. It also stops by itself: when the subject is lost for a while, when it settles inside the dead zone, or after `max_seconds`. `gain` is degrees of camera movement per pixel of offset -- a starting point, not a measurement. `invert` flips the direction, which is what a differently mounted camera needs: if the camera drives *away* from the subject, the sign is wrong for this mount, so read `track_status` and start again with invert true. Movement is capped at 25 degrees per iteration, so a badly wrong gain converges slowly rather than throwing the camera across its range.

Report what the follow loop is doing, with the evidence for each iteration. Every iteration appears with the measured offset and the step applied, so a loop that is driving the wrong way shows up as a residual distance that grows, and one whose moves the picture never confirms shows up in `move_failures` rather than as apparent success.

Stop following, and return the summary: what it saw, what it moved, what failed.

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.