@spec arange(integer(), integer(), integer(), mat_type()) :: maybe_mat_out()

Generate a Mat with shape {1, length}, where length is the amount of numbers starting from from to to with step size step

@spec arange(integer(), integer(), integer(), mat_type(), tuple()) :: maybe_mat_out()

Generate a Mat with a list of number starting from from to to with step size step. The generated Mat will then be reshaped to the requested shape if applicable.

@spec as_shape(maybe_mat_in(), tuple() | list()) :: maybe_mat_out()

This method does not change the underlying data. It only changes the steps when accessing the matrix.

If intended to change the underlying data to the new shape, please use Evision.Mat.reshape/2.

@spec channel_as_last_dim(maybe_mat_in()) :: maybe_mat_out()

This function does the opposite as to Evision.Mat.last_dim_as_channel/1.

If the number of channels of the input Evision.Mat is greater than 1, then this function would convert the input Evision.Mat with dims dims=list(int()) to a 1-channel Evision.Mat with dims [dims | channels].

If the number of channels of the input Evision.Mat is equal to 1,

• if dims == shape, then nothing happens

• otherwise, a new Evision.Mat that has dims=[dims | channels] will be returned

@spec channels(maybe_mat_in()) :: non_neg_integer() | {:error, String.t()}

The method returns the number of matrix channels.

@spec clone(maybe_mat_in()) :: maybe_mat_out()

Get a clone an Evision.Mat. Data will be copied to the resulting Evision.Mat.

@spec depth(maybe_mat_in()) :: maybe_mat_out()

Returns the depth of a matrix element.

The method returns the identifier of the matrix element depth (the type of each individual channel). For example, for a 16-bit signed element array, the method returns CV_16S. A complete list of matrix types contains the following values:

• CV_8U - 8-bit unsigned integers ( 0..255 )
• CV_8S - 8-bit signed integers ( -128..127 )
• CV_16U - 16-bit unsigned integers ( 0..65535 )
• CV_16S - 16-bit signed integers ( -32768..32767 )
• CV_32S - 32-bit signed integers ( -2147483648..2147483647 )
• CV_32F - 32-bit floating-point numbers ( -FLT_MAX..FLT_MAX, INF, NAN )
• CV_64F - 64-bit floating-point numbers ( -DBL_MAX..DBL_MAX, INF, NAN )

@spec elemSize1(maybe_mat_in()) :: integer()

Returns the size of each matrix element channel in bytes.

The method returns the matrix element channel size in bytes, that is, it ignores the number of channels. For example, if the matrix type is CV_16SC3 , the method returns sizeof(short) or 2.

@spec elemSize(maybe_mat_in()) :: integer()

Returns the matrix element size in bytes.

The method returns the matrix element size in bytes. For example, if the matrix type is CV_16SC3, the method returns 3*sizeof(short) or 6.

@spec empty() :: maybe_mat_out()

Create an empty Evision.Mat. This function is the Elixir equvilent of calling cv::Mat() in C++.

@spec fetch(t(), list() | integer()) :: {:ok, maybe_mat_out() | nil}

Access.fetch implementation for Evision.Mat.

iex> img = Evision.imread("test/qr_detector_test.png")
%Evision.Mat{
  channels: 3,
  dims: 2,
  type: {:u, 8},
  raw_type: 16,
  shape: {300, 300, 3},
  ref: #Reference<0.809884129.802291734.78316>
}

# Same behaviour as Nx.
# Also, img[0] gives the same result as img[[0]]
# For this example, they are both equvilent of img[[0, :all, :all]]
iex> img[[0]]
%Evision.Mat{
  channels: 3,
  dims: 2,
  type: {:u, 8},
  raw_type: 16,
  shape: {1, 300, 3},
  ref: #Reference<0.809884129.802291731.77296>
}

# same as img[[0..100, 50..200, :all]]
# however, currently we only support ranges with step size 1
#
# **IMPORTANT NOTE**
#
# also, please note that we are using Elixir.Range here
# and Elixir.Range is **inclusive**, i.e, [start, end]
# while cv::Range `{integer(), integer()}` is `[start, end)`
# the difference can be observed in the `shape` field
iex> img[[0..100, 50..200]]
%Evision.Mat{
  channels: 3,
  dims: 2,
  type: {:u, 8},
  raw_type: 16,
  shape: {101, 151, 3},
  ref: #Reference<0.809884129.802291731.77297>
}
iex> img[[{0, 100}, {50, 200}]]
%Evision.Mat{
  channels: 3,
  dims: 2,
  type: {:u, 8},
  raw_type: 16,
  shape: {100, 150, 3},
  ref: #Reference<0.809884129.802291731.77297>
}

# for this example, the result is the same as `Evision.extractChannel(img, 0)`
iex> img[[:all, :all, 0]]
%Evision.Mat{
  channels: 1,
  dims: 2,
  type: {:u, 8},
  raw_type: 0,
  shape: {300, 300},
  ref: #Reference<0.809884129.802291731.77298>
}
iex> img[[:all, :all, 0..1]]
%Evision.Mat{
  channels: 2,
  dims: 2,
  type: {:u, 8},
  raw_type: 8,
  shape: {300, 300, 2},
  ref: #Reference<0.809884129.802291731.77299>
}

# when index is out of bounds
iex> img[[:all, :all, 42]]
{:error, "index 42 is out of bounds for axis 2 with size 3"}

# it works the same way for any dimensional Evision.Mat
iex> mat = Evision.Mat.ones({10, 10, 10, 10, 10}, :u8)
iex> mat[[1..7, :all, 2..6, 3..9, :all]]
%Evision.Mat{
  channels: 1,
  dims: 5,
  type: {:u, 8},
  raw_type: 0,
  shape: {7, 10, 5, 7, 10},
  ref: #Reference<0.3015448455.3766878228.259075>
}

@spec from_binary(
  binary(),
  mat_type(),
  pos_integer(),
  pos_integer(),
  non_neg_integer()
) ::
  maybe_mat_out()

Create Mat from binary (pixel) data

• binary.

  The binary pixel data

• type.

  one of [{:u, 8}, {:s, 8}, {:u, 16}, {:s, 16}, {:s, 32}, {:f, 32}, {:f, 64}] and their corresponding shorthands.

• rows. int

  Number of rows (i.e., the height of the image)

• cols. int

  Number of cols (i.e., the width of the image)

• channels. int

  Number of channels.

@spec from_nx(Nx.t()) :: t() | {:error, String.t()}

Converts a tensor from Nx.Tensor to Evision.Mat.

Positional Arguments

• t. Nx.Tensor

Return

An Evision.Mat that has the same shape and type. (except for :s64, :u32 and :u64, please see more details at https://github.com/cocoa-xu/evision/issues/48).

@spec from_nx(Nx.Tensor.t(), tuple()) :: t() | {:error, String.t()}

Converts a tensor from Nx.Tensor to Evision.Mat.

Positional Arguments

• t. Nx.Tensor
• as_shape. tuple.

Return

An Evision.Mat that has the specified shape (if the number of elements matches) and the same type as the given tensor. (except for :s64, :u32 and :u64, please see more details at https://github.com/cocoa-xu/evision/issues/48).

@spec from_nx_2d(Nx.t()) :: t() | {:error, String.t()}

Converts a tensor from Nx.Tensor to a 2D Evision.Mat.

If the tuple size of the shape is 3, the resulting Evision.Mat will be a c-channel 2D image, where c is the last number in the shape tuple.

If the tuple size of the shape is 2, the resulting Evision.Mat will be a 1-channel 2D image.

Otherwise, it's not possible to convert the tensor to a 2D image.

@spec full(tuple(), number(), mat_type()) :: maybe_mat_out()

Generate a Mat with all of its elements equal to number.

Positional Arguments

• shape. tuple

  The expected shape of the resulting Evision.Mat

• number. number

  Element value.

• type.

  Value type.

@spec get_and_update(t(), term(), (t() -> t())) :: {t(), t()}

Access.get_and_update/3 implementation for Evision.Mat

iex> mat = Evision.Mat.zeros({5, 5}, :u8)
iex> Evision.Mat.to_nx(mat)
#Nx.Tensor<
  u8[5][5]
  Evision.Backend
  [
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0]
  ]
>
iex> {old, new} = Evision.Mat.get_and_update(mat, [1..3, 1..3], fn roi ->
    {roi, Nx.broadcast(Nx.tensor(255, type: roi.type), roi.shape)}
end)
iex> Evision.Mat.to_nx(new)
#Nx.Tensor<
  u8[5][5]
  Evision.Backend
  [
    [0, 0, 0, 0, 0],
    [0, 255, 255, 255, 0],
    [0, 255, 255, 255, 0],
    [0, 255, 255, 255, 0],
    [0, 0, 0, 0, 0]
  ]
>

@spec kino_render_image_encoding() :: term()

Get preferred image encoding when rendering in Kino.

Default value is Application.compile_env(:evision, :kino_render_image_encoding, :png).

@spec kino_render_image_max_size() :: term()

Get the maximum allowed image size to render in Kino.

Default value is Application.compile_env(:evision, :kino_render_image_max_size, {8192, 8192}).

@spec kino_render_tab_order() :: term()

Get preferred order of Kino.Layout tabs for Evision.Mat in Livebook.

Default value is Enum.uniq(Application.compile_env(:evision, :kino_render_tab_order, [:image, :raw, :numerical])).

@spec last_dim_as_channel(maybe_mat_in()) :: maybe_mat_out()

This function would convert the input tensor with dims [height, width, dims] to a dims-channel image with dims [height, width].

Note that OpenCV has limitation on the number of channels. Currently the maximum number of channels is 512.

Create an Evision.Mat from list literals.

Example

Creating Evision.Mat from empty list literal ([]) is the same as calling Evision.Mat.empty().

iex> Evision.Mat.literal!([])
%Evision.Mat{
  channels: 1,
  dims: 0,
  type: {:u, 8},
  raw_type: 0,
  shape: {},
  ref: #Reference<0.1204050731.2031747092.46781>
}

By default, the shape of the Mat will stay as is.

iex> Evision.Mat.literal!([[[1,1,1],[2,2,2],[3,3,3]]], :u8)
%Evision.Mat{
  channels: 1,
  dims: 3,
  type: {:u, 8},
  raw_type: 0,
  shape: {1, 3, 3},
  ref: #Reference<0.512519210.691404819.106300>
}

Evision.Mat.literal/3 will return a valid 2D image if the keyword argument, as_2d, is set to true and if the list literal can be represented as a 2D image.

iex> Evision.Mat.literal!([[[1,1,1],[2,2,2],[3,3,3]]], :u8, as_2d: true)
%Evision.Mat{
  channels: 3,
  dims: 2,
  type: {:u, 8},
  raw_type: 16,
  shape: {1, 3, 3},
  ref: #Reference<0.512519210.691404820.106293>
}

@spec pop(any(), any()) :: none()

Access.pop/2 is not implemented yet

@spec quicklook(Nx.Tensor.t()) :: Nx.Tensor.t()

@spec quicklook(t()) :: t()

@spec quicklook(term()) :: term()

Display inline image in terminal for iTerm2 users.

This function will check the value of :display_inline_image_iterm2 in the application config.

If is true, then it will detect if current session is running in iTerm2 (by checking the environment variable LC_TERMINAL).

If both are true, we next check if the image is a 2D image, also if its size is within the limits.

The maximum size can be set in the application config, for example,

config :evision, display_inline_image_iterm2: true
config :evision, display_inline_image_max_size: {8192, 8192}

If it passes all the checks, then it will be displayed as an inline image in iTerm2.

@spec raw_type(maybe_mat_in()) :: integer() | {:error, String.t()}

Returns the type of a matrix.

As Evision.Mat.type/1 returns the type used by Nx, this method gives the raw value of cv::Mat.type()

@spec roi(maybe_mat_in(), {integer(), integer(), integer(), integer()}) ::
  maybe_mat_out()

@spec roi(maybe_mat_in(), [{integer(), integer()} | Range.t() | :all]) ::
  maybe_mat_out()

Extracts a rectangular submatrix.

Variant 1

Positional Arguments

• mat. maybe_mat_in()

  The matrix.

• rect. {int, int, int, int}

  The rect that specifies {x, y, width, height}.

Return

Extracted submatrix specified as a rectangle. (data is copied)

Variant 2

Positional Arguments

• mat. maybe_mat_in()

  The matrix.

• ranges. [{int, int} | :all]

  Array of selected ranges along each array dimension.

Return

Extracted submatrix. (data is copied)

@spec roi(
  maybe_mat_in(),
  {integer(), integer()} | :all,
  {integer(), integer()} | :all
) ::
  maybe_mat_out()

@spec roi(maybe_mat_in(), Range.t(), Range.t()) :: maybe_mat_out()

Extracts a rectangular submatrix.

The submatrix data is copied.

Variant 1

Positional Arguments

• mat. maybe_mat_in()

  The matrix.

• rowRange. {int, int} | :all.

  Start and end row of the extracted submatrix. The upper boundary is not included.

• colRange. {int, int} | :all.

  Start and end column of the extracted submatrix. The upper boundary is not included.

Return

Extracted submatrix (data is copied).

Variant 2

Positional Arguments

• mat. maybe_mat_in()

  The matrix.

• rowRange. Range.t(step: 1).

  Start and end row of the extracted submatrix. The upper boundary is not included.

• colRange. Range.t(step: 1).

  Start and end column of the extracted submatrix. The upper boundary is not included.

Return

Extracted submatrix (data is copied).

@spec set_kino_render_image_encoding(:png | :jpeg | term()) :: term()

Set preferred image encoding when rendering in Kino.

Only valid when :kino >= 0.7 and using in livebook

Positional Arguments

• encoding. :png | :jpeg.

  When rendering a 2D image with Kino in Livebook the image will first be encoded into either :png or :jpeg

  • :png usually has better quality because it is lossless compression, however, it uses more bandwidth to transfer

  • :jpeg require less bandwidth to pass from the backend to the livebook frontend, but it is lossy compression

@spec set_kino_render_image_max_size({pos_integer(), pos_integer()}) :: term()

Set the maximum allowed image size to render in Kino.

Only valid when :kino >= 0.7 and using in livebook

Positional Arguments

• size. {height, width}.

@spec set_kino_render_tab_order([atom()] | term()) :: term()

Set preferred order of Kino.Layout tabs for Evision.Mat in Livebook.

Only valid when :kino >= 0.7 and using in Livebook.

Positional Arguments

• order: [atom()]

  Default order is [:image, :raw, :numerical], and the corresponding tabs will be:

  Image | Raw | Numerical

  Note that the :image tab will not show if the Evision.Mat is not a 2D image.

  Also, it's possible to specify any combination (any subset) of these tabs, including the empty one, [], and in that case, the output content in the livebook cell will be the same as :raw but without any tabs.

  Simply put, [] means to only do the basic inspect and not use Kino.Layout.tabs

  It's worth noting that [] != nil, because nil is default return value when kino_render_tab_order is not configured -- hence evision will use the default order, [:image, :raw, :numerical] in such case

  When only specifying one type, i.e., [:image], [:raw] or [:numerical], only one tab will be shown.

  Furthermore, when kino_render_tab_order is configured to [:image] and when the Evision.Mat is not a 2D image, it will automatically fallback to :raw.

  Simply put, [:image] in this case (when only specifying one type) means:

  displaying the Evision.Mat as an image whenever possible, and fallback to :raw if it's not a 2D image

@spec size(maybe_mat_in()) ::
  {non_neg_integer(), [non_neg_integer()]} | {:error, String.t()}

Returns the cv::MatSize of the matrix.

The method returns a tuple {dims, p} where dims is the number of dimensions, and p is a list with dims elements.

@spec to_nx(maybe_mat_in(), module()) :: Nx.Tensor.t() | {:error, String.t()}

Transform an Evision.Mat to Nx.tensor.

Positional Arguments

• mat: maybe_mat_in()

  Evision.Mat

• backend: module()

  Nx backend.

Return

If the input Evision.Mat represents a 2D image, the resulting tensor will have shape {height, width, channels}.

Example

iex> %Evision.Mat{} = mat = Evision.imread("/path/to/exist/img.png")
iex> nx_tensor = Evision.Mat.to_nx(mat)
#Nx.Tensor<
  u8[1080][1920][3]
  [[ ... pixel data ... ]]
>

Get raw pointers

@spec total(maybe_mat_in()) :: non_neg_integer() | {:error, String.t()}

Returns the total number of array elements.

The method returns the number of array elements (a number of pixels if the array represents an image).

@spec total(maybe_mat_in(), non_neg_integer(), non_neg_integer()) ::
  non_neg_integer() | {:error, String.t()}

Returns the total number of array elements.

The method returns the number of elements within a certain sub-array slice with start_dim <= dim < end_dim

@spec transpose(maybe_mat_in()) :: maybe_mat_out()

Transpose a matrix

Parameters

• mat. The matrix.

  by default it reverses the order of the axes.

@spec transpose(maybe_mat_in(), [integer()], Keyword.t()) :: maybe_mat_out()

Transpose a matrix

Parameters

• mat. Evision.Mat

• axes. [int]

  It must be a list which contains a permutation of [0,1,..,N-1] where N is the number of axes of mat. The i’th axis of the returned array will correspond to the axis numbered axes[i] of the input.

• opts. Keyword options.

  • as_shape. A tuple or list which overwrites the shape of the matrix (the total number of elements must be equal to the one as in its original shape). For example, a 4x4 matrix can be treated as a 2x2x2x2 matrix and transposed with axes=[2,1,3,0] in a single call.

    When specified, it combines the reshape and transpose operation in a single NIF call.

@spec type(maybe_mat_in()) :: mat_type() | {:error, String.t()}

This method returns the type-tuple used by Nx. To get the raw value of cv::Mat.type(), please use Evision.Mat.raw_type/1.