mita
31443b091f
- Created HS DollyCam HUD user manual (v1.3.0) detailing features, setup, commands, and troubleshooting. - Added FOV extension manual outlining FOV commands, usage in playlists, and dollyzoom functionality. - Introduced project context file for AI agents, specifying technology stack, critical implementation rules, and existing patterns.
262 lines
7.6 KiB
Plaintext
262 lines
7.6 KiB
Plaintext
0) IMPORTANT: RLVa REQUIRED
|
||
|
||
All FOV features in HS DollyCam require a viewer with RLVa support enabled.
|
||
Firestorm: Preferences → Firestorm → RLVa → “Enable RLVa”
|
||
If RLVa is OFF, the camera can still move, but FOV commands will do nothing.
|
||
|
||
HS DollyCam sets FOV via RLVa command:
|
||
@setcam_fov:<radians>=force
|
||
|
||
Notes:
|
||
- This is viewer-side. The HUD sends commands via owner chat.
|
||
- Some viewers show “executes: @setcam_fov:...” in chat even when scripts send “quiet”.
|
||
That display is a viewer setting and not HUD spam.
|
||
|
||
|
||
1) UNITS: Radians vs Degrees
|
||
|
||
FOV in HS DollyCam is stored internally in RADIANS.
|
||
|
||
Useful references:
|
||
- 60° = 1.04719755 rad
|
||
- 45° = 0.78539816 rad
|
||
- 30° = 0.52359878 rad
|
||
- 90° = 1.57079633 rad
|
||
|
||
Clamp range (safety):
|
||
- Minimum: 10°
|
||
- Maximum: 179°
|
||
|
||
|
||
2) STANDALONE FOV COMMANDS (Chat /88)
|
||
|
||
A) Set FOV in radians
|
||
/88 fov <rad>
|
||
|
||
Examples:
|
||
/88 fov 1.0472 (≈ 60°)
|
||
/88 fov 0.5236 (≈ 30°)
|
||
|
||
B) Set FOV in degrees
|
||
/88 fovdeg <deg>
|
||
|
||
Examples:
|
||
/88 fovdeg 60
|
||
/88 fovdeg 35
|
||
|
||
C) Convenience heuristic:
|
||
If you use /88 fov with a value > 3.2 it is assumed to be degrees.
|
||
Example:
|
||
/88 fov 60 (interpreted as 60°, not 60 rad)
|
||
|
||
|
||
3) FOV IN PLAYLIST NOTECARDS
|
||
|
||
You can set FOV from a playlist notecard as standalone lines.
|
||
|
||
Syntax:
|
||
fov <rad> [quiet]
|
||
fovdeg <deg> [quiet]
|
||
|
||
quiet:
|
||
- 1 = quiet (default)
|
||
- 0 = show debug output (if enabled) / more visible logs
|
||
|
||
Examples:
|
||
fovdeg 60
|
||
fovdeg 35 1
|
||
fov 1.0472
|
||
fov 0.7854 1
|
||
|
||
Tip:
|
||
If you run a playlist with a gap_ms, FOV lines follow the same pacing rules.
|
||
|
||
|
||
4) PRESETS: SAVING / STORING FOV
|
||
|
||
HS DollyCam presets store camera position + focus + rotation + FOV.
|
||
|
||
- Presets are saved in Linkset Data slots “P<idx>”
|
||
- v2 preset format includes FOV as the 11th field:
|
||
field index 10 = fovRad
|
||
|
||
Workflow:
|
||
1) Move camera where you want it.
|
||
2) Set FOV you want (RLVa required), e.g.:
|
||
/88 fovdeg 35
|
||
3) Save the preset:
|
||
/88 save 1
|
||
|
||
Important:
|
||
- The HUD stores the “last set by HUD” FOV as a fallback.
|
||
- Best practice: explicitly set FOV, then save, for reliable dollyzoom.
|
||
|
||
|
||
5) APPLYING PRESET FOV (Load / MoveTo)
|
||
|
||
When you load or moveto a preset, HS DollyCam can apply the preset’s stored FOV.
|
||
|
||
A) Chat:
|
||
/88 load <idx> (cut)
|
||
/88 moveto <idx> [ms] (animated)
|
||
|
||
B) Menu / Markers:
|
||
- Clicking a marker or using the menu load/moveto applies preset FOV if present.
|
||
|
||
C) Playlists:
|
||
- In playlists, moveto/load lines also apply preset FOV (outside tours).
|
||
|
||
Notes:
|
||
- If a preset has no stored FOV, camera movement still works; FOV stays unchanged.
|
||
|
||
|
||
6) TOUR FOV: KEYFRAME RAMP DURING TOURS
|
||
|
||
Tours are continuous rides through multiple waypoints.
|
||
You can optionally ramp FOV during a tour.
|
||
|
||
A) Tour blocks in notecards:
|
||
tour <total_ms> [mode]
|
||
moveto <idx1> [optional weight tokens]
|
||
moveto <idx2> ...
|
||
fovdeg <degA> <degB> (optional, can be inside tour block)
|
||
wait <ms> (hold at the last waypoint)
|
||
endtour
|
||
|
||
B) Fast compact tour (chat or notecard):
|
||
/88 tour <ms> [mode] <idx1> <idx2> ... [fovdeg <a> <b>]
|
||
/88 tour <ms> [mode] <idx1> <idx2> ... [fov <radA> <radB>]
|
||
tour <ms> [mode] <idx1> <idx2> ... [fovdeg <a> <b>]
|
||
tour <ms> [mode] <idx1> <idx2> ... [fov <radA> <radB>]
|
||
|
||
Example:
|
||
/88 tour 8000 spline 1 2 3 4 fovdeg 35 70
|
||
tour 8000 spline 1 2 3 4 fovdeg 35 70
|
||
|
||
What it does:
|
||
- Camera moves along the tour path
|
||
- FOV is interpolated from A → B based on path progress (weighted distance)
|
||
- FOV ticks are throttled (about 10 Hz) + deduped
|
||
|
||
Tip:
|
||
FOV ramps in tours are a creative tool (stylized “zoom breathing”), not a perfect “dollyzoom”.
|
||
|
||
|
||
7) DOLLYZOOM (Classic)
|
||
|
||
DollyZoom is a 2-point tour that changes camera distance while counter-changing FOV.
|
||
|
||
Chat syntax:
|
||
/88 dollyzoom <ms> [mode] <idxA> <idxB>
|
||
|
||
Chat/menu DollyZoom and one-line tours use HS_CamTourCommands.lsl.
|
||
|
||
Notecard syntax:
|
||
dollyzoom <ms> [mode] <idxA> <idxB>
|
||
|
||
Examples:
|
||
/88 dollyzoom 4000 linear 1 2
|
||
/88 dollyzoom 4000 1 2
|
||
dollyzoom 5000 spline 3 4
|
||
|
||
How it works:
|
||
- Builds an internal 2-point TOUR from preset A to preset B
|
||
- Uses FOV stored in preset A and preset B:
|
||
FOV ramps from fovA → fovB across the move
|
||
|
||
Requirements:
|
||
- BOTH presets must have FOV stored (unless using “keep”, see below)
|
||
- Best results when both presets look at the same subject (same focus point)
|
||
|
||
|
||
8) DOLLYZOOM keep (Keepframe / constant framing)
|
||
|
||
The current build supports “keepframe” with the “keep” option:
|
||
|
||
Chat:
|
||
/88 dollyzoom <ms> [mode] <idxA> <idxB> keep
|
||
|
||
Notecard:
|
||
dollyzoom <ms> [mode] <idxA> <idxB> keep
|
||
|
||
Goal:
|
||
- Keep the apparent size of the subject as constant as possible while moving.
|
||
|
||
How it works (math):
|
||
- Let d(t) = distance between camera position and the “motif focus”
|
||
- Define K from the start frame:
|
||
K = d0 * tan(FOV0/2)
|
||
- Then compute FOV per tick:
|
||
FOV(t) = 2 * atan( K / d(t) )
|
||
|
||
What is “motif focus”?
|
||
- If LOCK is ON, motif focus comes from the LOCK target (object position + offset).
|
||
- If LOCK is OFF, motif focus is fixed to “focA” (focus from the first dolly preset).
|
||
- Many setups also force focB = focA automatically for keep to avoid focus drift.
|
||
|
||
Requirements:
|
||
- RLVa ON (for FOV updates)
|
||
- A meaningful distance change (camera must move closer/farther to the subject)
|
||
- Best when the focus corresponds to the actual subject (not an arbitrary point)
|
||
|
||
When to use LOCK with keep:
|
||
- Use LOCK when the subject moves (avatar walking, vehicle, animated object).
|
||
- If the subject is static and focA is correct, you do not need LOCK.
|
||
|
||
Notes / Limitations (Second Life reality):
|
||
- Viewer camera smoothing (Camera Lag/Focus Lag) can make keepframe look “off”
|
||
because the visible camera lags behind the scripted target position.
|
||
- FOV updates are throttled and deduped; tiny changes may not be sent every frame.
|
||
- Expect “usable” results, not perfect cinema-grade dollyzoom.
|
||
|
||
Performance note:
|
||
- Tour FOV updates are intentionally throttled and deduped.
|
||
- Tour camera frame updates are also capped by HS_CamEngine.properties:
|
||
tour_cam_min_interval=0.033
|
||
tour_pos_epsilon=0.005
|
||
tour_focus_epsilon=0.005
|
||
- Lower move_step values make the path computation run more often, but they do
|
||
not send camera frames faster than tour_cam_min_interval unless that value is
|
||
lowered too. Lower values increase script load.
|
||
|
||
|
||
9) QUALITY TIPS (Practical)
|
||
|
||
A) For a strong dollyzoom:
|
||
- Make presets with a BIG distance difference (e.g. 3m → 15m)
|
||
- Keep focus on the same subject point (focA == focB), or use LOCK
|
||
- Use moderate FOV ranges (e.g. 30° → 70°)
|
||
|
||
B) If it looks “mushy” or delayed:
|
||
- Reduce camera lag settings (Engine properties):
|
||
move_pos_lag / move_focus_lag too high will cause visible trailing.
|
||
- Consider lowering smoothing for recording, then increase for casual viewing.
|
||
|
||
C) If dollyzoom looks like “just moving camera”:
|
||
- Your distance to focus might not be changing (dA ≈ dB).
|
||
- Your focus might be drifting (focA and focB are different, or moving with camera).
|
||
- The camera path may be sideways/orbit rather than in/out.
|
||
|
||
|
||
10) TROUBLESHOOTING
|
||
|
||
Problem: “FOV commands do nothing”
|
||
- RLVa is OFF or viewer doesn’t support RLVa.
|
||
- Enable RLVa in viewer settings.
|
||
|
||
Problem: “Chat shows executes: @setcam_fov...”
|
||
- That is viewer-side display.
|
||
- HUD already uses quiet mode where possible.
|
||
|
||
Problem: “Dollyzoom says it needs FOV in both presets”
|
||
- Set FOV, then save preset A and preset B again:
|
||
/88 fovdeg 35
|
||
/88 save 1
|
||
/88 fovdeg 70
|
||
/88 save 2
|
||
|
||
Problem: “keep doesn’t feel like dollyzoom”
|
||
- Ensure camera distance to motif changes substantially.
|
||
- Ensure motif focus is correct (LOCK target or correct focA).
|
||
- Lower camera lag (smoothing) if needed.
|