defmodule Evision.Mat do
@moduledoc """
Evision Mat
"""
require Logger
import Kernel, except: [abs: 1, floor: 1, ceil: 1, round: 1]
@behaviour Access
@typedoc """
Types for `Evision.Mat`
#### Shorthand
- `:u8`
- `:u16`
- `:s16`
- `:s32`
- `:f32`
- `:f64`
- `:f16`
#### Tuple Form
- `{:u, 8}`
- `{:u, 16}`
- `{:s, 8}`
- `{:s, 16}`
- `{:s, 32}`
- `{:f, 32}`
- `{:f, 64}`
- `{:f, 16}`
"""
@type mat_type ::
{:u, 8 | 16}
| {:s, 8 | 16 | 32}
| {:f, 32 | 64 | 16}
| :u8
| :u16
| :s8
| :s16
| :s32
| :f32
| :f64
| :f16
@type mat_type_tuple_form ::
{:u, 8 | 16}
| {:s, 8 | 16 | 32}
| {:f, 32 | 64 | 16}
@typedoc """
Type that represents an `Evision.Mat` struct.
- **channels**: `int`.
The number of matrix channels.
- **dims**: `int`.
Matrix dimensionality.
- **type**: `mat_type`.
Type of the matrix elements, following `:nx`'s convention.
- **raw_type**: `int`.
The raw value returned from `int cv::Mat::type()`.
- **shape**: `tuple`.
The shape of the matrix.
- **ref**: `reference`.
The underlying erlang resource variable.
"""
@type t :: %__MODULE__{
channels: integer(),
dims: integer(),
type: mat_type(),
raw_type: integer(),
shape: tuple(),
ref: reference()
}
@enforce_keys [:channels, :dims, :type, :raw_type, :shape, :ref]
defstruct [:channels, :dims, :type, :raw_type, :shape, :ref]
alias __MODULE__, as: T
@typedoc """
The resulting ok-error tuple when a NIF function can return `Evision.Mat`.
"""
@type maybe_mat_out :: Evision.Mat.t() | {:error, String.t()}
@typedoc """
Input argument, `Evision.Mat`, `Nx.Tensor` or `#reference`.
- `Evision.Mat`, recommended to use.
- `Nx.Tensor`
Accepting this type so that it's easier to interact with a `Nx.Tensor`.
- `reference()`, not recommended.
Only some internal functions will pass the raw reference variables around.
"""
@type maybe_mat_in :: reference() | Evision.Mat.t() | Nx.Tensor.t()
@doc false
def __to_struct__(%{
:channels => channels,
:dims => dims,
:type => type,
:raw_type => raw_type,
:shape => shape,
:ref => ref
}) do
%T{
channels: channels,
dims: dims,
type: type,
raw_type: raw_type,
shape: shape,
ref: ref
}
end
def __to_struct__(ret) do
Evision.Internal.Structurise.to_struct(ret)
end
@doc false
@spec __from_struct__(Evision.Mat.t() | Nx.Tensor.t() | reference()) :: reference()
def __from_struct__(%T{ref: ref}) do
ref
end
def __from_struct__(%Nx.Tensor{} = tensor) do
Evision.Internal.Structurise.from_struct(tensor)
end
def __from_struct__(ref) when is_reference(ref) do
ref
end
@doc false
@spec __from_elixir_range__(Range.t(), Keyword.t()) :: {number(), number()}
def __from_elixir_range__(first..last//step, opts \\ []) do
swap_if_neg_step = opts[:swap_if_neg_step] || false
allowed_step_size = opts[:allowed_step_size]
if is_list(allowed_step_size) and !Enum.member?(allowed_step_size, step) do
raise "Invalid step size, only supports step size in #{inspect({allowed_step_size})} at the moment."
end
if swap_if_neg_step and step < 0 do
{last, first}
else
{first, last}
end
end
@doc false
def __standardise_range_list__(ranges, inclusive_range) do
Enum.map(ranges, fn r ->
case r do
:all ->
:all
{first, last} ->
# {_, _} is cv::Range
# hence we don't need to do anything to it
{first, last}
first..last//step ->
# first..last//step is Elixir.Range
# 0..0 should give [0] if `inclusive_range` is true
{first, last} = __from_elixir_range__(first..last//step, allowed_step_size: [1])
if inclusive_range do
# note that what we are going return is cv::Range
# which is [start, end)
{first, last + 1}
else
{first, last}
end
number when is_integer(number) ->
# cv::Range is [start, end)
# while Elixir.Range is [first, last]
if inclusive_range do
# [first, last), [0, 1) will give [0]
# note that what we are going return is cv::Range
# which is [start, end)
{number, number + 1}
else
# [first, last], [0, 0] will give []
{number, number}
end
unknown ->
raise "Cannot convert from `#{inspect(unknown)}` to a valid range."
end
end)
end
@doc """
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 roi(maybe_mat_in(), {integer(), integer()} | :all, {integer(), integer()} | :all) ::
maybe_mat_out()
def roi(mat, rowRange, colRange)
when (is_tuple(rowRange) or rowRange == :all) and (is_tuple(colRange) or colRange == :all) do
mat = __from_struct__(mat)
:evision_nif.mat_roi(mat: mat, rowRange: rowRange, colRange: colRange)
|> Evision.Internal.Structurise.to_struct()
end
@spec roi(maybe_mat_in(), Range.t(), Range.t()) :: maybe_mat_out()
def roi(mat, firstRow..lastRow//1, firstCol..lastCol//1) do
roi(mat, {firstRow, lastRow}, {firstCol, lastCol})
end
def roi(_, _.._//_, _.._//_) do
raise ArgumentError, "Evision.Mat.roi does not support step size other than 1."
end
@doc """
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(), integer(), integer()}) :: maybe_mat_out()
def roi(mat, rect = {_, _, _, _}) when is_tuple(rect) do
mat = __from_struct__(mat)
:evision_nif.mat_roi(mat: mat, rect: rect)
|> Evision.Internal.Structurise.to_struct()
end
@spec roi(maybe_mat_in(), [{integer(), integer()} | Range.t() | :all]) :: maybe_mat_out()
def roi(mat, ranges) when is_list(ranges) do
mat = __from_struct__(mat)
ranges = __standardise_range_list__(ranges, true)
:evision_nif.mat_roi(mat: mat, ranges: ranges)
|> Evision.Internal.Structurise.to_struct()
end
@spec update_roi(maybe_mat_in(), [{integer(), integer()} | Range.t() | :all], maybe_mat_in()) ::
maybe_mat_out()
def update_roi(mat, ranges, with_mat) do
mat = __from_struct__(mat)
ranges = __standardise_range_list__(ranges, true)
with_mat = __from_struct__(with_mat)
:evision_nif.mat_update_roi(mat: mat, ranges: ranges, with_mat: with_mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc """
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,
```elixir
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 quicklook(Nx.Tensor.t()) :: Nx.Tensor.t()
def quicklook(%Nx.Tensor{} = tensor) do
case Evision.Mat.from_nx_2d(tensor) do
%Evision.Mat{} = mat ->
quicklook(mat)
end
tensor
end
@spec quicklook(Evision.Mat.t()) :: Evision.Mat.t()
def quicklook(%Evision.Mat{dims: dims, channels: c, shape: shape} = mat) do
if Application.get_env(:evision, :display_inline_image_max_size) == :error do
Application.put_env(:evision, :display_inline_image_max_size, {8192, 8192}, persistent: true)
end
is_2d_image =
(dims == 2 and Enum.member?([1, 3, 4], c)) or
(c == 1 and tuple_size(shape) == 3 and elem(shape, 2) == 1)
with {:is_2d, true} <- {:is_2d, is_2d_image},
{:display_image_if_in_iterm2, {:ok, true}} <-
{:display_image_if_in_iterm2,
Application.fetch_env(:evision, :display_inline_image_iterm2)},
{:is_iterm2, true} <- {:is_iterm2, System.get_env("LC_TERMINAL") == "iTerm2"},
{:get_maximum_size, {h, w}} <-
{:get_maximum_size, Application.get_env(:evision, :display_inline_image_max_size)},
{:within_maximum_size, true} <-
{:within_maximum_size,
((0 < h and elem(shape, 0) < h) or h == :infinity) and
((0 < w and elem(shape, 1) < w) or w == :infinity)} do
{osc, st} =
if String.starts_with?(System.get_env("TERM"), "screen") do
{"\ePtmux;\e\e", "\a\e\\\r\n"}
else
{"\e", "\e\\\r\n"}
end
binary = Evision.imencode(".png", mat)
b64 = Base.encode64(binary)
bin_size = byte_size(binary)
IO.puts([
"#{osc}]1337;File=size=#{bin_size};inline=1:",
b64,
st
])
end
mat
end
@spec quicklook(term()) :: term()
def quicklook(any) do
any
end
@default_kino_render_image_encoding Application.compile_env(:evision, :kino_render_image_encoding, :png)
@doc """
Get preferred image encoding when rendering in Kino.
Default value is `Application.compile_env(:evision, :kino_render_image_encoding, :png)`.
"""
@spec kino_render_image_encoding() :: term()
def kino_render_image_encoding() do
Process.get(:evision_kino_render_image_encoding, @default_kino_render_image_encoding)
end
@doc """
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_encoding(:png | :jpeg | term()) :: term()
def set_kino_render_image_encoding(encoding) when encoding in [:png, :jpeg] do
Process.put(:evision_kino_render_image_encoding, encoding)
end
def set_kino_render_image_encoding(encoding) do
raise RuntimeError, """
Unknown image encoding `#{inspect(encoding)}`. Supported encoding are either :png or :jpeg.
"""
end
@default_kino_render_image_max_size Application.compile_env(:evision, :kino_render_image_max_size, {8192, 8192})
@doc """
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_image_max_size() :: term()
def kino_render_image_max_size() do
Process.get(:evision_kino_render_image_max_size, @default_kino_render_image_max_size)
end
@doc """
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_image_max_size({pos_integer(), pos_integer()}) :: term()
def set_kino_render_image_max_size({height, width}) when is_integer(height) and height > 0 and is_integer(width) and width > 0 do
Process.put(:evision_kino_render_image_max_size, {height, width})
end
def set_kino_render_image_max_size(size) do
raise RuntimeError, """
Invalid value for setting image max size `#{inspect(size)}`, expecting a 2-tuple with positive integers, `{height, width}`.
"""
end
@kino_render_tab_order Enum.uniq(Application.compile_env(:evision, :kino_render_tab_order, [:image, :raw, :numerical]))
@doc """
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 kino_render_tab_order() :: term()
def kino_render_tab_order() do
Process.get(:evision_kino_render_tab_order, @kino_render_tab_order)
end
@supported_kino_render_tab_order [:image, :raw, :numerical]
@doc """
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 set_kino_render_tab_order([atom()] | term()) :: term()
def set_kino_render_tab_order(order) when is_list(order) do
render_types =
Enum.map(order, fn t ->
supported? = Enum.member?(@supported_kino_render_tab_order, t)
if !supported? do
Logger.warning """
Unknown type `#{inspect(t)}` found in `config :evision, kino_render_tab_order`.
Supported types are `#{inspect(@supported_kino_render_tab_order)}` and their combinations.
"""
nil
else
t
end
end)
|> Enum.reject(fn a -> a == nil end)
Process.put(:evision_kino_render_tab_order, render_types)
end
def set_kino_render_tab_order(types) do
raise RuntimeError, """
Unknown types `#{inspect(types)}`. Supported types are `#{inspect(@supported_kino_render_tab_order)}` and their combinations.
"""
end
if Code.ensure_loaded?(Kino.Render) do
defimpl Kino.Render do
require Logger
defp is_2d_image(%Evision.Mat{dims: 2}), do: true
defp is_2d_image(%Evision.Mat{channels: 1, shape: {_h, _w, 1}}) do
true
end
defp is_2d_image(_), do: false
defp within_maximum_size(mat) do
{max_height, max_width} = Evision.Mat.kino_render_image_max_size()
case Evision.Mat.shape(mat) do
{h, w} ->
h <= max_height and w <= max_width
{h, w, _c} ->
h <= max_height and w <= max_width
_ ->
false
end
end
@spec to_livebook(Evision.Mat.t()) :: Kino.Output.t()
def to_livebook(mat) when is_struct(mat, Evision.Mat) do
render_types = Evision.Mat.kino_render_tab_order()
Enum.map(render_types, fn
:raw ->
{"Raw", Kino.Inspect.new(mat)}
:numerical ->
{"Numerical", Kino.Inspect.new(Evision.Mat.to_nx(mat))}
:image ->
{ext, format} =
case Evision.Mat.kino_render_image_encoding() do
:jpg ->
{".jpg", :jpeg}
:jpeg ->
{".jpeg", :jpeg}
:png ->
{".png", :png}
unknown ->
raise RuntimeError, "Cannot render image with encoding `#{inspect(unknown)}`"
end
with true <- is_2d_image(mat),
true <- within_maximum_size(mat),
encoded <- Evision.imencode(ext, mat),
true <- is_binary(encoded) do
{"Image", Kino.Image.new(encoded, format)}
else
_ ->
nil
end
end)
|> Enum.reject(fn a -> a == nil end)
|> to_livebook_tabs(render_types, mat)
end
defp to_livebook_tabs([], [:image], mat) do
Kino.Layout.tabs([{"Raw", Kino.Inspect.new(mat)}])
|> Kino.Render.to_livebook()
end
defp to_livebook_tabs(_tabs, [], mat) do
Kino.Inspect.new(mat)
|> Kino.Render.to_livebook()
end
defp to_livebook_tabs(tabs, _types, _mat) do
Kino.Layout.tabs(tabs)
|> Kino.Render.to_livebook()
end
end
end
@doc false
def __generate_complete_range__(dims, maybe_incomplete) when is_list(maybe_incomplete) do
indices_given = Enum.count(maybe_incomplete)
if indices_given <= dims do
maybe_incomplete ++ List.duplicate(:all, dims - indices_given)
else
if indices_given == dims + 1 do
maybe_incomplete
else
{:error,
"too many indices, got #{indices_given} index ranges, while the matrix.dims is #{dims}"}
end
end
end
@impl Access
@doc """
Access.fetch implementation for Evision.Mat.
```elixir
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 fetch(Evision.Mat.t(), list() | integer()) :: {:ok, maybe_mat_out() | nil}
def fetch(mat, key) when is_list(key) do
ranges = __generate_complete_range__(mat.dims, key)
ranges = __standardise_range_list__(ranges, true)
{:ok, roi(mat, ranges)}
end
def fetch(mat, key) when is_integer(key) do
# cv::Range is [start, end)
fetch(mat, [{key, key + 1}])
end
def fetch(_mat, _key) do
{:ok, nil}
end
@impl Access
@doc """
Access.get_and_update/3 implementation for Evision.Mat
```elixir
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 get_and_update(Evision.Mat.t(), term(), (Evision.Mat.t() -> Evision.Mat.t())) ::
{Evision.Mat.t(), Evision.Mat.t()}
def get_and_update(mat, key, function) when is_list(key) do
ranges = __generate_complete_range__(mat.dims, key)
roi = roi(mat, ranges)
case function.(roi) do
{^roi, modified_roi} ->
if is_struct(modified_roi, Nx.Tensor) or is_struct(modified_roi, Evision.Mat) do
{mat, update_roi(mat, ranges, modified_roi)}
else
raise RuntimeError,
"Cannot update the requested sub-matrix with unsupported value #{inspect(modified_roi)}"
end
_ ->
{mat, mat}
end
end
def get_and_update(mat, key, function) when is_integer(key) do
get_and_update(mat, [{key, key + 1}], function)
end
def get_and_update(_mat, key, _function) do
raise RuntimeError, "Evision.Mat.get_and_update/3: unknown/unsupported key #{inspect(key)}"
end
@impl Access
@doc """
Access.pop/2 is not implemented yet
"""
@spec pop(any, any) :: none
def pop(_mat, _key) do
raise RuntimeError, "Evision.Mat does not support Access.pop/2 yet"
end
@doc namespace: :"cv.Mat"
@doc """
Create an `Evision.Mat` from list literals.
### Example
Creating `Evision.Mat` from empty list literal (`[]`) is the same as calling `Evision.Mat.empty()`.
```elixir
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.
```elixir
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.
```elixir
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 literal(list(), mat_type(), Keyword.t()) :: maybe_mat_out()
def literal([]) do
empty()
end
def literal(literal, type, opts \\ [])
def literal([], _type, _opts) do
empty()
end
def literal(literal, type, opts) when is_list(literal) do
# leave all the checks to Nx.tensor/2
as_2d_image = opts[:as_2d] || false
tensor = Nx.tensor(literal, type: type, backend: Evision.Backend)
if as_2d_image do
Evision.Mat.from_nx_2d(tensor)
else
Evision.Mat.from_nx(tensor)
end
end
@doc namespace: :"cv.Mat"
@spec number(number(), mat_type()) :: maybe_mat_out()
def number(number, type) do
type = check_unsupported_type(type)
Evision.Mat.full({1, 1}, number, type)
end
@doc namespace: :"cv.Mat"
@spec at(maybe_mat_in(), integer()) :: number() | {:error, String.t()}
def at(mat, position) when is_integer(position) and position >= 0 do
mat = __from_struct__(mat)
:evision_nif.mat_at(img: mat, pos: position)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec add(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def add(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_add(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec add(maybe_mat_in(), maybe_mat_in(), mat_type()) :: maybe_mat_out()
def add(lhs, rhs, type) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
{t, l} = check_unsupported_type(type)
:evision_nif.mat_add_typed(lhs: lhs, rhs: rhs, t: t, l: l)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec subtract(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def subtract(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_subtract(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec subtract(maybe_mat_in(), maybe_mat_in(), mat_type()) :: maybe_mat_out()
def subtract(lhs, rhs, type) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
{t, l} = check_unsupported_type(type)
:evision_nif.mat_subtract_typed(lhs: lhs, rhs: rhs, t: t, l: l)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec multiply(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def multiply(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_multiply(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec multiply(maybe_mat_in(), maybe_mat_in(), mat_type()) :: maybe_mat_out()
def multiply(lhs, rhs, type) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
{t, l} = check_unsupported_type(type)
:evision_nif.mat_multiply_typed(lhs: lhs, rhs: rhs, t: t, l: l)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec matrix_multiply(maybe_mat_in(), maybe_mat_in(), mat_type() | nil) :: maybe_mat_out()
def matrix_multiply(lhs, rhs, out_type \\ nil)
def matrix_multiply(lhs, rhs, nil) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_matrix_multiply(lhs: lhs, rhs: rhs, t: nil, l: 0)
|> Evision.Internal.Structurise.to_struct()
end
def matrix_multiply(lhs, rhs, out_type) when is_atom(out_type) do
{t, l} = check_unsupported_type(out_type)
matrix_multiply(lhs, rhs, {t, l})
end
def matrix_multiply(lhs, rhs, {t, l}) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_matrix_multiply(lhs: lhs, rhs: rhs, t: t, l: l)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec divide(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def divide(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_divide(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec divide(maybe_mat_in(), maybe_mat_in(), mat_type()) :: maybe_mat_out()
def divide(lhs, rhs, type) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
{t, l} = check_unsupported_type(type)
:evision_nif.mat_divide_typed(lhs: lhs, rhs: rhs, t: t, l: l)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec bitwise_and(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def bitwise_and(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_bitwise_and(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec bitwise_or(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def bitwise_or(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_bitwise_or(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec bitwise_xor(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def bitwise_xor(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_bitwise_xor(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec cmp(maybe_mat_in(), maybe_mat_in(), :eq | :gt | :ge | :lt | :le | :ne) :: maybe_mat_out()
def cmp(lhs, rhs, op) when op in [:eq, :gt, :ge, :lt, :le, :ne] do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_cmp(l: lhs, r: rhs, type: op)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec logical_and(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def logical_and(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_logical_and(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec logical_or(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def logical_or(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_logical_or(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec logical_xor(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def logical_xor(lhs, rhs) do
lhs = __from_struct__(lhs)
rhs = __from_struct__(rhs)
:evision_nif.mat_logical_xor(l: lhs, r: rhs)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec abs(maybe_mat_in()) :: maybe_mat_out()
def abs(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_abs(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec expm1(maybe_mat_in()) :: maybe_mat_out()
def expm1(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_expm1(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec clip(maybe_mat_in(), number(), number()) :: maybe_mat_out()
def clip(mat, lower, upper)
when is_number(lower) and is_number(upper) and lower <= upper do
mat = __from_struct__(mat)
:evision_nif.mat_clip(img: mat, lower: lower, upper: upper)
|> Evision.Internal.Structurise.to_struct()
end
@doc """
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
```elixir
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 ... ]]
>
```
"""
@spec to_nx(maybe_mat_in(), module()) :: Nx.Tensor.t() | {:error, String.t()}
def to_nx(mat, backend \\ Evision.Backend) when is_struct(mat, Evision.Mat) do
mat = __from_struct__(mat)
with mat_type <- Evision.Mat.type(mat),
mat_shape <- Evision.Mat.shape(mat),
{:not_empty_shape, true} <- {:not_empty_shape, tuple_size(mat_shape) > 0},
{:not_error, true, _} <- {:not_error, elem(mat_shape, 0) != :error, mat_shape},
bin <- Evision.Mat.to_binary(mat),
{:is_binary, true, _} <- {:is_binary, is_binary(bin), bin} do
Nx.reshape(Nx.from_binary(bin, mat_type, backend: backend), mat_shape)
else
{:error, reason} ->
{:error, reason}
{:not_empty_shape, false} ->
{:error, "shape is {}"}
{:not_error, false, error} ->
error
{:is_binary, false, error} ->
error
end
end
@doc """
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.t()) :: Evision.Mat.t() | {:error, String.t()}
def from_nx(t) when is_struct(t, Nx.Tensor) do
case Nx.shape(t) do
{} ->
Evision.Mat.from_binary_by_shape(Nx.to_binary(t), Nx.type(t), {1})
shape ->
Evision.Mat.from_binary_by_shape(Nx.to_binary(t), Nx.type(t), shape)
end
end
@doc """
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(Nx.Tensor.t(), tuple()) :: Evision.Mat.t() | {:error, String.t()}
def from_nx(t, as_shape) when is_struct(t, Nx.Tensor) do
case Nx.shape(t) do
{} ->
Evision.Mat.from_binary_by_shape(Nx.to_binary(t), Nx.type(t), {1})
shape ->
if Tuple.product(shape) == Tuple.product(as_shape) do
Evision.Mat.from_binary_by_shape(Nx.to_binary(t), Nx.type(t), as_shape)
else
{:error,
"cannot convert tensor(#{inspect(shape)}) to mat as shape #{inspect(as_shape)}"}
end
end
end
@doc """
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 from_nx_2d(Nx.t()) :: Evision.Mat.t() | {:error, String.t()}
def from_nx_2d(t) do
case Nx.shape(t) do
{height, width} ->
Evision.Mat.from_binary(Nx.to_binary(t), Nx.type(t), height, width, 1)
{height, width, channels} ->
Evision.Mat.from_binary(Nx.to_binary(t), Nx.type(t), height, width, channels)
shape ->
{:error, "Cannot convert tensor(#{inspect(shape)}) to a 2D image"}
end
end
@doc """
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 transpose(maybe_mat_in(), [integer()], Keyword.t()) :: maybe_mat_out()
def transpose(mat, axes, opts \\ []) do
mat = __from_struct__(mat)
self_shape =
case shape(mat) do
{:error, msg} ->
raise RuntimeError, msg
self_shape ->
Tuple.to_list(self_shape)
end
as_shape = opts[:as_shape] || self_shape
as_shape =
case is_tuple(as_shape) do
true ->
Tuple.to_list(as_shape)
_ ->
as_shape
end
ndims = Enum.count(as_shape)
uniq_axes =
Enum.uniq(axes)
|> Enum.reject(fn axis ->
axis < 0 or axis > ndims
end)
if Enum.count(uniq_axes) != ndims do
{:error, "invalid transpose axes #{inspect(axes)} for shape #{inspect(as_shape)}"}
else
as_shaped = as_shape != self_shape
:evision_nif.mat_transpose(
img: mat,
axes: uniq_axes,
as_shape: as_shape,
as_shaped: as_shaped
)
|> Evision.Internal.Structurise.to_struct()
end
end
@doc """
Transpose a matrix
## Parameters
- `mat`. The matrix.
by default it reverses the order of the axes.
"""
@spec transpose(maybe_mat_in()) :: maybe_mat_out()
def transpose(mat) do
mat = __from_struct__(mat)
with {:error, message} <- shape(mat) do
{:error, message}
else
as_shape ->
ndims = Enum.count(as_shape)
uniq_axes = Enum.reverse(0..(ndims - 1))
:evision_nif.mat_transpose(img: mat, axes: uniq_axes, as_shape: as_shape)
|> Evision.Internal.Structurise.to_struct()
end
end
@doc namespace: :"cv.Mat"
@doc """
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`.
"""
@spec type(maybe_mat_in()) :: mat_type() | {:error, String.t()}
def type(mat)
def type(%T{type: type}) do
type
end
def type(mat) when is_struct(mat) do
mat = Evision.Internal.Structurise.from_struct(mat)
:evision_nif.mat_type(img: mat)
end
def type(mat) when is_reference(mat) do
:evision_nif.mat_type(img: mat)
end
@doc namespace: :"cv.Mat"
@spec bitwise_not(maybe_mat_in()) :: maybe_mat_out()
def bitwise_not(mat) do
mat = __from_struct__(mat)
case Evision.Mat.type(mat) do
{:error, msg} ->
{:error, msg}
type ->
{s, _} = check_unsupported_type(type)
if s in [:s, :u] do
:evision_nif.mat_bitwise_not(img: mat)
|> Evision.Internal.Structurise.to_struct()
else
{:error,
"bitwise operators expect integer tensors as inputs and outputs an integer tensor, got: #{inspect(type)}"}
end
end
end
@doc namespace: :"cv.Mat"
@spec ceil(maybe_mat_in()) :: maybe_mat_out()
def ceil(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_ceil(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec floor(maybe_mat_in()) :: maybe_mat_out()
def floor(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_floor(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec negate(maybe_mat_in()) :: maybe_mat_out()
def negate(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_negate(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec round(maybe_mat_in()) :: maybe_mat_out()
def round(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_round(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec sign(maybe_mat_in()) :: maybe_mat_out()
def sign(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_sign(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec setTo(maybe_mat_in(), number(), maybe_mat_in()) :: maybe_mat_out()
def setTo(mat, value, mask) do
mat = __from_struct__(mat)
mask = __from_struct__(mask)
:evision_nif.mat_set_to(img: mat, value: value, mask: mask)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec dot(maybe_mat_in(), maybe_mat_in()) :: maybe_mat_out()
def dot(mat_a, mat_b) do
mat_a = __from_struct__(mat_a)
mat_b = __from_struct__(mat_b)
:evision_nif.mat_dot(a: mat_a, b: mat_b)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec as_type(maybe_mat_in(), mat_type()) :: maybe_mat_out()
def as_type(mat, type)
def as_type(mat, type) when is_atom(type) do
as_type(mat, check_unsupported_type(type))
end
def as_type(mat, {t, l}) when is_atom(t) and l > 0 do
mat = __from_struct__(mat)
:evision_nif.mat_as_type(img: mat, t: t, l: l)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec shape(maybe_mat_in()) :: tuple() | {:error, String.t()}
def shape(mat)
def shape(%T{shape: shape}) do
shape
end
def shape(mat) when is_struct(mat) do
mat = Evision.Internal.Structurise.from_struct(mat)
:evision_nif.mat_shape(img: mat)
end
def shape(mat) when is_reference(mat) do
:evision_nif.mat_shape(img: mat)
end
@doc namespace: :"cv.Mat"
@doc """
The method returns the number of matrix channels.
"""
@spec channels(maybe_mat_in()) :: non_neg_integer() | {:error, String.t()}
def channels(mat)
def channels(%T{channels: channels}) do
channels
end
def channels(mat) when is_struct(mat) do
mat = Evision.Internal.Structurise.from_struct(mat)
:evision_nif.mat_type(img: mat)
end
def channels(mat) when is_reference(mat) do
:evision_nif.mat_channels(img: mat)
end
@doc namespace: :"cv.Mat"
@doc """
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 depth(maybe_mat_in()) :: maybe_mat_out()
def depth(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_depth(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@doc """
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 raw_type(maybe_mat_in()) :: integer() | {:error, String.t()}
def raw_type(%T{raw_type: raw_type}) do
raw_type
end
def raw_type(mat) when is_struct(mat) do
mat = Evision.Internal.Structurise.from_struct(mat)
:evision_nif.mat_raw_type(img: mat)
end
def raw_type(mat) when is_reference(mat) do
:evision_nif.mat_raw_type(img: mat)
end
@doc namespace: :"cv.Mat"
@spec isSubmatrix(maybe_mat_in()) :: true | false
def isSubmatrix(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_isSubmatrix(img: mat)
end
@doc namespace: :"cv.Mat"
@spec isContinuous(maybe_mat_in()) :: true | false
def isContinuous(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_isContinuous(img: mat)
end
@doc namespace: :"cv.Mat"
@doc """
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 elemSize(maybe_mat_in()) :: integer()
def elemSize(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_elemSize(img: mat)
end
@doc namespace: :"cv.Mat"
@doc """
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 elemSize1(maybe_mat_in()) :: integer()
def elemSize1(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_elemSize1(img: mat)
end
@doc namespace: :"cv.Mat"
@doc """
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 size(maybe_mat_in()) :: {non_neg_integer(), [non_neg_integer()]} | {:error, String.t()}
def size(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_size(img: mat)
end
@doc namespace: :"cv.Mat"
@doc """
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() | {:error, String.t()}
def total(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_total(img: mat, start_dim: -1, end_dim: 0xFFFFFFFF)
end
@doc namespace: :"cv.Mat"
@doc """
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 total(maybe_mat_in(), non_neg_integer(), non_neg_integer()) ::
non_neg_integer() | {:error, String.t()}
def total(mat, start_dim, end_dim \\ 0xFFFFFFFF) do
mat = __from_struct__(mat)
:evision_nif.mat_total(img: mat, start_dim: start_dim, end_dim: end_dim)
end
@doc namespace: :"cv.Mat"
@doc """
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`.
"""
@spec last_dim_as_channel(maybe_mat_in()) :: maybe_mat_out()
def last_dim_as_channel(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_last_dim_as_channel(src: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc """
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 channel_as_last_dim(maybe_mat_in()) :: maybe_mat_out()
def channel_as_last_dim(mat) when is_struct(mat) do
mat = Evision.Internal.Structurise.from_struct(mat)
channel_as_last_dim(mat)
end
def channel_as_last_dim(mat) when is_reference(mat) do
with {:error, msg} <- size(mat) do
{:error, msg}
else
{num_dims, _} ->
with {:error, msg} <- shape(mat) do
{:error, msg}
else
shape ->
num_shape = tuple_size(shape)
if num_shape == num_dims do
mat
else
Evision.Mat.as_shape(mat, shape)
end
end
end
end
@doc namespace: :"cv.Mat"
@spec zeros(tuple(), mat_type()) :: maybe_mat_out()
def zeros(shape, type) when is_tuple(shape) do
{t, l} = check_unsupported_type(type)
:evision_nif.mat_zeros(
shape: Tuple.to_list(shape),
t: t,
l: l
)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec ones(tuple(), mat_type()) :: maybe_mat_out()
def ones(shape, type) when is_tuple(shape) do
{t, l} = check_unsupported_type(type)
:evision_nif.mat_ones(
shape: Tuple.to_list(shape),
t: t,
l: l
)
|> Evision.Internal.Structurise.to_struct()
end
@doc """
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()) :: maybe_mat_out()
def arange(from, to, step, type) when step != 0 do
{t, l} = check_unsupported_type(type)
arange =
:evision_nif.mat_arange(
from: from,
to: to,
step: step,
t: t,
l: l
)
mat = Evision.Internal.Structurise.to_struct(arange)
with %Evision.Mat{} <- mat,
ret = {length, _} <- Evision.Mat.shape(mat),
{:mat_shape_error, false, _} <- {:mat_shape_error, length == :error, ret} do
Evision.Mat.reshape(mat, {1, length})
else
{:mat_shape_error, true, error} ->
error
{:error, msg} ->
{:error, msg}
end
end
@doc """
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 arange(integer(), integer(), integer(), mat_type(), tuple()) :: maybe_mat_out()
def arange(from, to, step, type, shape) when step != 0 do
{t, l} = check_unsupported_type(type)
with {:ok, mat} <-
:evision_nif.mat_arange(
from: from,
to: to,
step: step,
t: t,
l: l
) do
Evision.Mat.reshape(mat, shape)
else
error -> error
end
end
@doc """
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 full(tuple(), number(), mat_type()) :: maybe_mat_out()
def full(shape, number, type) do
{t, l} = check_unsupported_type(type)
:evision_nif.mat_full(
number: number,
t: t,
l: l,
shape: Tuple.to_list(shape)
)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@doc """
Get a clone an `Evision.Mat`.
Data will be copied to the resulting `Evision.Mat`.
"""
@spec clone(maybe_mat_in()) :: maybe_mat_out()
def clone(mat) do
mat = __from_struct__(mat)
:evision_nif.mat_clone(img: mat)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@doc """
Create an empty `Evision.Mat`.
This function is the Elixir equvilent of calling `cv::Mat()` in C++.
"""
@spec empty() :: maybe_mat_out()
def empty() do
:evision_nif.mat_empty()
|> Evision.Internal.Structurise.to_struct()
end
@spec to_batched(maybe_mat_in(), non_neg_integer(), Keyword.t()) :: maybe_mat_out()
def to_batched(mat, batch_size, opts)
when is_integer(batch_size) and batch_size >= 1 and is_list(opts) do
leftover = opts[:leftover] || :repeat
mat = __from_struct__(mat)
with {:error, msg} <- shape(mat) do
{:error, msg}
else
as_shape ->
:evision_nif.mat_to_batched(
img: mat,
batch_size: batch_size,
as_shape: as_shape,
leftover: leftover
)
|> Evision.Internal.Structurise.to_struct()
end
end
@spec to_batched(maybe_mat_in(), non_neg_integer(), tuple(), Keyword.t()) :: maybe_mat_out()
def to_batched(mat, batch_size, as_shape, opts)
when is_integer(batch_size) and batch_size >= 1 and is_tuple(as_shape) and is_list(opts) do
mat = __from_struct__(mat)
leftover = opts[:leftover] || :repeat
:evision_nif.mat_to_batched(
img: mat,
batch_size: batch_size,
as_shape: Tuple.to_list(as_shape),
leftover: leftover
)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec to_binary(maybe_mat_in(), non_neg_integer()) :: binary() | {:error, String.t()}
def to_binary(mat, limit \\ 0) when is_integer(limit) and limit >= 0 do
mat = __from_struct__(mat)
:evision_nif.mat_to_binary(img: mat, limit: limit)
end
@doc """
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.
"""
@doc namespace: :"cv.Mat"
@spec from_binary(binary(), mat_type(), pos_integer(), pos_integer(), non_neg_integer()) ::
maybe_mat_out()
def from_binary(binary, type, rows, cols, channels)
def from_binary(binary, type, rows, cols, channels)
when is_binary(binary) and rows > 0 and cols > 0 and channels > 0 and is_atom(type) do
from_binary(binary, check_unsupported_type(type), rows, cols, channels)
end
def from_binary(binary, _type = {t, l}, rows, cols, channels)
when is_binary(binary) and rows > 0 and cols > 0 and channels > 0 and
is_atom(t) and is_integer(l) do
:evision_nif.mat_from_binary(
binary: binary,
t: t,
l: l,
cols: cols,
rows: rows,
channels: channels
)
|> Evision.Internal.Structurise.to_struct()
end
@spec check_unsupported_type(mat_type()) :: mat_type_tuple_form()
defp check_unsupported_type({:f, 32} = type), do: type
defp check_unsupported_type({:f, 64} = type), do: type
defp check_unsupported_type({:u, 8} = type), do: type
defp check_unsupported_type({:u, 16} = type), do: type
defp check_unsupported_type({:s, 8} = type), do: type
defp check_unsupported_type({:s, 16} = type), do: type
defp check_unsupported_type({:s, 32} = type), do: type
defp check_unsupported_type(:f32), do: {:f, 32}
defp check_unsupported_type(:f64), do: {:f, 64}
defp check_unsupported_type(:u8), do: {:u, 8}
defp check_unsupported_type(:u16), do: {:u, 16}
defp check_unsupported_type(:s8), do: {:s, 8}
defp check_unsupported_type(:s16), do: {:s, 16}
defp check_unsupported_type(:s32), do: {:s, 32}
defp check_unsupported_type(type) do
case type do
{t, l} when is_atom(t) and l > 0 ->
:ok
type when is_atom(type) ->
:ok
true ->
raise_unsupported_type(type)
end
new_type =
with {:ok, unsupported_type_map} <- Application.fetch_env(:evision, :unsupported_type_map) do
Map.get(unsupported_type_map, type, :error)
else
_ -> :error
end
if new_type == :error do
raise_unsupported_type(type)
else
check_unsupported_type(new_type)
end
end
defp raise_unsupported_type(type) do
raise ArgumentError,
"#{inspect(type)} is not supported by OpenCV. However, it is possible to set an " <>
"`unsupported_type_map` in config/config.exs to allow evision do type conversion automatically. " <>
"Please see https://github.com/cocoa-xu/evision#unsupported-type-map for more details and examples."
end
@doc namespace: :"cv.Mat"
@spec from_binary_by_shape(binary(), mat_type(), tuple()) :: maybe_mat_out()
def from_binary_by_shape(binary, type, shape)
def from_binary_by_shape(binary, type, shape)
when is_binary(binary) and is_atom(type) and is_tuple(shape) do
from_binary_by_shape_impl(binary, check_unsupported_type(type), shape)
end
def from_binary_by_shape(binary, {t, l}, shape)
when is_binary(binary) and is_atom(t) and is_integer(l) and is_tuple(shape) do
from_binary_by_shape_impl(binary, {t, l}, shape)
end
defp from_binary_by_shape_impl(binary, {t, l}, shape)
when is_binary(binary) and is_atom(t) and is_integer(l) and is_tuple(shape) do
:evision_nif.mat_from_binary_by_shape(
binary: binary,
t: t,
l: l,
shape: Tuple.to_list(shape)
)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec eye(non_neg_integer(), mat_type()) :: maybe_mat_out()
def eye(n, type) when is_integer(n) and n > 0 do
{t, l} = check_unsupported_type(type)
:evision_nif.mat_eye(
n: n,
t: t,
l: l
)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@spec reshape(maybe_mat_in(), tuple() | list()) :: maybe_mat_out()
def reshape(mat, shape)
def reshape(mat, shape) when is_tuple(shape) do
mat = __from_struct__(mat)
:evision_nif.mat_reshape(
mat: mat,
shape: Tuple.to_list(shape)
)
|> Evision.Internal.Structurise.to_struct()
end
def reshape(mat, shape) when is_list(shape) do
mat = __from_struct__(mat)
:evision_nif.mat_reshape(
mat: mat,
shape: shape
)
|> Evision.Internal.Structurise.to_struct()
end
@doc namespace: :"cv.Mat"
@doc """
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 as_shape(maybe_mat_in(), tuple() | list()) :: maybe_mat_out()
def as_shape(mat, as_shape)
def as_shape(mat, as_shape) when is_tuple(as_shape) do
as_shape(mat, Tuple.to_list(as_shape))
end
def as_shape(mat, as_shape) when is_list(as_shape) do
mat = __from_struct__(mat)
case Evision.Mat.shape(mat) do
{:error, msg} ->
{:error, msg}
old_shape ->
if Tuple.product(old_shape) == Enum.product(as_shape) do
:evision_nif.mat_as_shape(
img: mat,
as_shape: as_shape
)
|> Evision.Internal.Structurise.to_struct()
else
{:error,
"Cannot treat mat with shape #{inspect(old_shape)} as the requested new shape #{inspect(as_shape)}: mismatching number of elements"}
end
end
end
@spec squeeze(maybe_mat_in()) :: maybe_mat_out()
def squeeze(mat) do
mat = __from_struct__(mat)
case Evision.Mat.shape(mat) do
{:error, msg} ->
{:error, msg}
mat_shape ->
shape = Tuple.to_list(mat_shape)
Evision.Mat.reshape(mat, Enum.reject(shape, fn d -> d == 1 end))
end
end
@spec broadcast_to(maybe_mat_in(), tuple()) :: maybe_mat_out()
def broadcast_to(mat, to_shape) do
mat = __from_struct__(mat)
:evision_nif.mat_broadcast_to(
img: mat,
to_shape: Tuple.to_list(to_shape),
force_src_shape: []
)
|> Evision.Internal.Structurise.to_struct()
end
@spec broadcast_to(maybe_mat_in(), tuple(), tuple()) :: maybe_mat_out()
def broadcast_to(mat, to_shape, force_src_shape) do
mat = __from_struct__(mat)
:evision_nif.mat_broadcast_to(
img: mat,
to_shape: Tuple.to_list(to_shape),
force_src_shape: Tuple.to_list(force_src_shape)
)
|> Evision.Internal.Structurise.to_struct()
end
end
