View Source Image.Video (image v0.21.0)

Implements functions to extract frames froma video file as images using eVision.

Images can be extracted by frame number of number of milliseconds with Image.Video.image_from_video/2.

In order to extract images the video file must first be opened with Image.Video.open/1. At the end of processing the video file should be closed with Image.Video.close/1.

This process can be wrrapped by Image.Video.with_video/2 which will open a video file, execute a function (passing it the video reference) and closing the video file at the end of the function.

Link to this section Summary

Types

The valid options for Image.Video.seek/2, Image.Video.image_from_video/2

The representation of a video stream

Functions

Closes a video.

Closes a video or raises an exception.

Extracts a frame from a video and returns an image.

Extracts a frame from a video and returns an image or raises an exception.

Guards that a frame offset is valid for a video

Guards that a millisecond count is valid for a video

Opens a video file or video stream for frame extraction.

Opens a video file for frame extraction or raises an exception.

Seeks the video head to a specified frame offset or millisecond offset.

Seeks the video head to a specified frame offset or millisecond offset.

Opens a video file, calls the given function with the video reference and closes the video after the function returns.

Link to this section Types

@type seek_options() ::
  [{:frame, non_neg_integer()}] | [{:millisecond, non_neg_integer()}]

The valid options for Image.Video.seek/2, Image.Video.image_from_video/2

@type stream_id() :: non_neg_integer() | :default_camera

The representation of a video stream

Link to this section Functions

@spec close(Evision.VideoCapture.t()) ::
  {:ok, Evision.VideoCapture.t()} | {:error, Image.error_message()}

Closes a video.

arguments

Arguments

returns

Returns

  • {:ok, closed_video} or

  • {:error, reason}

example

Example

iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> Image.Video.close(video)

Closes a video or raises an exception.

arguments

Arguments

returns

Returns

  • closed_video or

  • raises an exception.

example

Example

iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> Image.Video.close!(video)
Link to this function

image_from_video(video, options \\ [])

View Source
@spec image_from_video(Evision.VideoCapture.t(), seek_options()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Extracts a frame from a video and returns an image.

After the image is extracted the play head in the video file is advanced one frame. That is, successive calls to Image.Video.image_from_video/2 will return successive frames - not the same frame.

arguments

Arguments

options

Options

  • unit is either :frame or :millisecond with a non-negative integer offset. For example frame: 3. The default is [] which means that no seek is performed and the extracted image is taken from the current position in the file or video stream.

returns

Returns

  • {:ok, image} or

  • {:error, reason}

notes

Notes

Seeking cannot be performed on image streams such as webcams. Therefore no options may be provided when extracting images from an image stream.

warning

Warning

This frame extraction is NOT atomic. First the read head is set to the frame of interest, then the frame is extracted and decoded. It is possible for another process to interleave its own seek operation resulting in undefined results.

examples

Examples

iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> {:ok, _image} = Image.Video.image_from_video(video)
iex> {:ok, _image} = Image.Video.image_from_video(video, frame: 0)
iex> {:ok, _image} = Image.Video.image_from_video(video, millisecond: 1_000)
iex> {:error, "Offset for :frame must be a positive integer. Found -1"} = Image.Video.image_from_video(video, frame: -1)
iex> {:error, "Offset for :frame is too large"} = Image.Video.image_from_video(video, frame: 500)
Link to this function

image_from_video!(video, options \\ [])

View Source
@spec image_from_video!(Evision.VideoCapture.t(), seek_options()) ::
  Vix.Vips.Image.t() | no_return()

Extracts a frame from a video and returns an image or raises an exception.

After the image is extracted the play head in the video file is advanced one frame. That is, successive calls to Image.Video.image_from_video/2 will return successive frames - not the same frame.

arguments

Arguments

options

Options

  • unit is either :frame or :millisecond with a non-negative integer offset. For example frame: 3. The default is [] which means that no seek is performed and the extracted image is taken from the current position in the file or video stream.

returns

Returns

  • image or

  • raises an exception

notes

Notes

Seeking cannot be performed on image streams such as webcams. Therefore no options may be provided when extracting images from an image stream.

warning

Warning

This frame extraction is NOT atomic. First the read head is set to the frame of interest, then the frame is extracted and decoded. It is possible for another process to interleave its own seek operation resulting in undefined results.

Link to this macro

is_frame(frame, frame_count)

View Source (macro)

Guards that a frame offset is valid for a video

Link to this macro

is_valid_millis(millis, frames, fps)

View Source (macro)

Guards that a millisecond count is valid for a video

@spec open(filename_or_stream :: Path.t() | stream_id()) ::
  {:ok, Evision.VideoCapture.t()} | {:error, Image.error_message()}

Opens a video file or video stream for frame extraction.

arguments

Arguments

  • filename_or_stream is the filename of a video file or the OpenCV representation of a video stream as an integer. It may also be :default_camera to open the default camera if there is one.

returns

Returns

  • {:ok, video} or

  • {:error, reason}

example

Example

iex> Image.Video.open "./test/support/video/video_sample.mp4"
iex> {:ok, camera_video} = Image.Video.open(:default_camera)
iex> Image.Video.close(camera_video)
Link to this function

open!(filename_or_stream)

View Source
@spec open!(filename_or_stream :: Path.t() | stream_id()) ::
  Evision.VideoCapture.t() | no_return()

Opens a video file for frame extraction or raises an exception.

arguments

Arguments

  • filename is the filename of a video file

returns

Returns

  • video or

  • raises an exception

example

Example

iex> Image.Video.open! "./test/support/video/video_sample.mp4"

Seeks the video head to a specified frame offset or millisecond offset.

Note that seeking a video format is supported, seeking a live video stream (such as from a webcam) is not supported and will return an error.

arguments

Arguments

options

Options

  • unit is either :frame or :millisecond with a non-negative integer offset. For example frame: 3.

returns

Returns

  • {:ok, video} or

  • {:error, reason}

notes

Notes

Seeking cannot be performed on image streams such as webcams. Therefore no options may be provided when extracting images from an image stream.

examples

Examples

iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> {:ok, _image} = Image.Video.seek(video, frame: 0)
iex> {:ok, _image} = Image.Video.seek(video, millisecond: 1_000)
iex> {:error, "Offset for :frame must be a positive integer. Found -1"} =
...>   Image.Video.seek(video, frame: -1)
Link to this function

seek!(video, options \\ [])

View Source

Seeks the video head to a specified frame offset or millisecond offset.

Note that seeking a video format is supported, seeking a live video stream (such as from a webcam) is not supported and will return an error.

arguments

Arguments

options

Options

  • unit is either :frame or :millisecond with a non-negative integer offset. For example frame: 3.

returns

Returns

  • {:ok, video} or

  • {:error, reason}

notes

Notes

Seeking cannot be performed on image streams such as webcams. Therefore no options may be provided when extracting images from an image stream.

Link to this function

with_video(filename, fun)

View Source
@spec with_video(filename :: Path.t(), (Evision.VideoCapture.t() -> any())) ::
  {:ok, Evision.VideoCapture.t()} | {:error, Image.error_message()}

Opens a video file, calls the given function with the video reference and closes the video after the function returns.

arguments

Arguments

  • filename is the filename of a video file

returns

Returns

  • {:ok, video} or

  • {:error, reason}

example

Example

iex> Image.Video.with_video "./test/support/video/video_sample.mp4", fn video ->
...>  Image.Video.image_from_video(video, 1)
...> end