Script Shooting Hooks

Introduction

CHDK 1.3 adds "hooks" which allow Lua scripts pause the shooting process when certain point are reached.

Development thread http://chdk.setepontos.com/index.php?topic=11081.msg108530#msg108530

Available hooks

There are currently 3 hooks defined (in order of execution)

hook_preshoot

Executes in shooting_expo_param_override, after CHDK overrides are applied. Can be used to adjust exposure settings after the camera has calculated it's own values. This hook only executes once per half press cycle, so if shooting in continuous mode, it will only be reached once before the continuous burst starts.

hook_shoot

Executes very shortly before the shutter would open, in wait_until_remote_button_is_released (prior to the actual remote check). Can used to control the start of the exposure, to synchronize with an external process or to make continuous mode shoot at a specific interval.

Adjusting exposure, focus and zoom parameters here is not recommended. Exposure parameters will generally not take effect for the current shot. Zoom or focus may work, but the camera would not normally expect them to be manipulated at this point.

hook_raw

Executes in raw_process, after shot_histogram has built the raw histogram and DNG exif has been captured, but before any raw or DNG file has been written. It can be used to adjust the exposure for a following shot in continuous mode.

CHDK 1.4 adds the ability to directly read and write the raw buffer while in the raw hook, using Raw Hook Operations.

Hook functions

Each of the hook is available in Lua as a table which contains a standard set of functions:

hook.set(timeout)

Enables the hook, so it will block the shooting process for up to timeout milliseconds. 0 disables the hook. Hooks are cleared when a script ends. They are not cleared between shots.

If timeout milliseconds pass without a call from continue, the shooting process will proceed as if continue had been called.

hook.is_ready()

returns true when the shooting process is stopped in the hook.

Note: A hook may never become ready (for example, if shooting fails), so code that waits for a hook should implement a timeout. Using hookutil wait_ready() is suggested.

hook.continue()

Allows the shooting process to continue from the hook point.

hook.count()

Returns a count of how many times the hook has been reached for this script. This allows you to tell if a particular point has been reached without actually blocking the process.

hookutil Lua module

The hookutil Lua module adds an additional convenience method

hook.wait_ready()

Usage

status=hook_name.wait_ready([opts])

opts is an optional table which may contain

• timeout: number of ms to wait for hook to be ready, default 10 seconds
• timeout_error: boolean - if true (default), throw an error if timeout expires otherwise unset hook and return false
• raw_adj_tv: boolean - if true (default) add shutter time to raw hook timeout added in CHDK 1.4
• raw_adj_dfs: boolean, -- if true (default) and raw_adj_tv is true, double shutter time wait if dark frame likely added in CHDK 1.4

Known issues

Setting ISO in hook_preshoot may not work correctly on some cameras (those that require shooting_expo_iso_override in the capt_seq code)

A few ports may call shooting_expo_param_override more than once. On these ports, hook_preshoot will also be called more than once per shot.

A few ports may be missing wait_until_remote_button_is_released. On these ports, hook_shutter will not be reached.

There is no simple way to tell if a hook timed out.

The shoot() function cannot be used with shoot hooks, since it blocks for the entire shooting process. Use key presses with shoot_half and shoot_full.