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
video
is anyEvision.VideoCapture.t/0
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)
@spec close!(Evision.VideoCapture.t()) :: Evision.VideoCapture.t() | no_return()
Closes a video or raises an exception.
arguments
Arguments
video
is anyEvision.VideoCapture.t/0
returns
Returns
closed_video
orraises an exception.
example
Example
iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> Image.Video.close!(video)
@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
video
is anyEvision.VideoCapture.t/0
options
is a keyword list of options. The defalt
options
Options
unit
is either:frame
or:millisecond
with a non-negative integer offset. For exampleframe: 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)
@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
video
is anyEvision.VideoCapture.t/0
options
is a keyword list of options
options
Options
unit
is either:frame
or:millisecond
with a non-negative integer offset. For exampleframe: 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
orraises 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.
Guards that a frame offset is valid for a video
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)
@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
orraises an exception
example
Example
iex> Image.Video.open! "./test/support/video/video_sample.mp4"
@spec seek(Evision.VideoCapture.t(), seek_options()) :: {:ok, Evision.VideoCapture.t()} | {:error, Image.error_message()}
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
video
is anyEvision.VideoCapture.t/0
options
is a keyword list of options
options
Options
unit
is either:frame
or:millisecond
with a non-negative integer offset. For exampleframe: 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)
@spec seek!(Evision.VideoCapture.t(), seek_options()) :: Evision.VideoCapture.t() | no_return()
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
video
is anyEvision.VideoCapture.t/0
options
is a keyword list of options
options
Options
unit
is either:frame
or:millisecond
with a non-negative integer offset. For exampleframe: 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.
@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