.. _stdlib_stbimage_boost:

=====================================
High-level image API (stbimage_boost)
=====================================

.. das:module:: stbimage_boost

High-level image API built on stbimage and raster. Provides the Image struct with load, save, resize, flip, crop, blit, and format conversion.



++++++++++
Structures
++++++++++

.. _struct-stbimage_boost-Image:

.. das:attribute:: Image

Image container with raw pixel data in original format.
``bpc`` (bytes per component): 1 = uint8, 2 = uint16, 4 = float.
``channels``: 1 = grey, 2 = grey+alpha, 3 = RGB, 4 = RGBA.

:Fields: * **bytes** : array<uint8> - Raw pixel data stored as a byte array.

         * **width** : int - Width of the image in pixels.

         * **height** : int - Height of the image in pixels.

         * **channels** : int - Number of color channels (1=grey, 2=grey+alpha, 3=RGB, 4=RGBA).

         * **bpc** : int - Bytes per component (1=uint8, 2=uint16, 4=float).



.. _function-stbimage_boost_Image_rq_valid_Image_0x5c:

.. das:function:: Image.valid() : bool

def Image.valid

.. _function-stbimage_boost_Image_rq_stride_Image_0x62:

.. das:function:: Image.stride() : int

def Image.stride

.. _function-stbimage_boost_Image_rq_has_alpha_Image_0x68:

.. das:function:: Image.has_alpha() : bool

def Image.has_alpha

.. _function-stbimage_boost_Image_rq_pixel_size_Image_0x6e:

.. das:function:: Image.pixel_size() : int

def Image.pixel_size

.. _function-stbimage_boost_Image_rq_is_hdr_Image_0x74:

.. das:function:: Image.is_hdr() : bool

def Image.is_hdr

.. _function-stbimage_boost_Image_rq_data_size_Image_0x7a:

.. das:function:: Image.data_size() : int

def Image.data_size

.. _function-stbimage_boost_Image_rq_load_Image_string_int_0x82:

.. das:function:: Image.load(path: string; requested_channels: int = 0) : tuple<bool;string>

def Image.load

:Arguments: * **path** : string

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_load_hdr_Image_string_int_0x8f:

.. das:function:: Image.load_hdr(path: string; requested_channels: int = 0) : tuple<bool;string>

def Image.load_hdr

:Arguments: * **path** : string

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_load_16_Image_string_int_0x9c:

.. das:function:: Image.load_16(path: string; requested_channels: int = 0) : tuple<bool;string>

def Image.load_16

:Arguments: * **path** : string

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_load_from_memory_Image_array_ls_uint8_gr__int_0xab:

.. das:function:: Image.load_from_memory(data: array<uint8>; requested_channels: int = 0) : tuple<bool;string>

def Image.load_from_memory

:Arguments: * **data** : array<uint8>

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_load_from_memory_Image_array_ls_uint8_gr__hh__int_0xb1:

.. das:function:: Image.load_from_memory(data: array<uint8>#; requested_channels: int = 0) : tuple<bool;string>

def Image.load_from_memory

:Arguments: * **data** : array<uint8>\ #

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_load_hdr_from_memory_Image_array_ls_uint8_gr__int_0xb7:

.. das:function:: Image.load_hdr_from_memory(data: array<uint8>; requested_channels: int = 0) : tuple<bool;string>

def Image.load_hdr_from_memory

:Arguments: * **data** : array<uint8>

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_load_hdr_from_memory_Image_array_ls_uint8_gr__hh__int_0xbd:

.. das:function:: Image.load_hdr_from_memory(data: array<uint8>#; requested_channels: int = 0) : tuple<bool;string>

def Image.load_hdr_from_memory

:Arguments: * **data** : array<uint8>\ #

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_load_16_from_memory_Image_array_ls_uint8_gr__int_0xc3:

.. das:function:: Image.load_16_from_memory(data: array<uint8>; requested_channels: int = 0) : tuple<bool;string>

def Image.load_16_from_memory

:Arguments: * **data** : array<uint8>

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_load_16_from_memory_Image_array_ls_uint8_gr__hh__int_0xc9:

.. das:function:: Image.load_16_from_memory(data: array<uint8>#; requested_channels: int = 0) : tuple<bool;string>

def Image.load_16_from_memory

:Arguments: * **data** : array<uint8>\ #

            * **requested_channels** : int

.. _function-stbimage_boost_Image_rq_save_Image_string_int_0xd1:

.. das:function:: Image.save(path: string; quality: int = 0) : tuple<bool;string>

def Image.save

:Arguments: * **path** : string

            * **quality** : int

.. _function-stbimage_boost_Image_rq_encode_Image_string_array_ls_uint8_gr__int_0xf1:

.. das:function:: Image.encode(format: string; out_data: array<uint8>; quality: int = 0) : tuple<bool;string>

def Image.encode

:Arguments: * **format** : string

            * **out_data** : array<uint8>

            * **quality** : int

.. _function-stbimage_boost_Image_rq_resize_Image_int_int_0x119:

.. das:function:: Image.resize(new_w: int; new_h: int) : Image

def Image.resize

:Arguments: * **new_w** : int

            * **new_h** : int

.. _function-stbimage_boost_Image_rq_resize_Image_int_int_stbir_filter_0x11f:

.. das:function:: Image.resize(new_w: int; new_h: int; filter: stbir_filter) : Image

def Image.resize

:Arguments: * **new_w** : int

            * **new_h** : int

            * **filter** :  :ref:`stbir_filter <enum-stbimage-stbir_filter>`

.. _function-stbimage_boost_Image_rq_flip_vertical_Image_0x133:

.. das:function:: Image.flip_vertical() : Image

def Image.flip_vertical

.. _function-stbimage_boost_Image_rq_flip_horizontal_Image_0x143:

.. das:function:: Image.flip_horizontal() : Image

def Image.flip_horizontal

.. _function-stbimage_boost_Image_rq_crop_Image_int_int_int_int_0x167:

.. das:function:: Image.crop(cx: int; cy: int; cw: int; ch: int) : Image

def Image.crop

:Arguments: * **cx** : int

            * **cy** : int

            * **cw** : int

            * **ch** : int

.. _function-stbimage_boost_Image_rq_blit_Image_Image_int_int_0x183:

.. das:function:: Image.blit(src: Image; dst_x: int; dst_y: int)

def Image.blit

:Arguments: * **src** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **dst_x** : int

            * **dst_y** : int

.. _function-stbimage_boost_Image_rq_fill_rect_Image_int_int_int_int_uint_0x1ae:

.. das:function:: Image.fill_rect(x: int; y: int; w: int; h: int; color: uint)

def Image.fill_rect

:Arguments: * **x** : int

            * **y** : int

            * **w** : int

            * **h** : int

            * **color** : uint

.. _function-stbimage_boost_Image_rq_fill_rect_Image_int_int_int_int_uint8_0x1be:

.. das:function:: Image.fill_rect(x: int; y: int; w: int; h: int; val: uint8)

def Image.fill_rect

:Arguments: * **x** : int

            * **y** : int

            * **w** : int

            * **h** : int

            * **val** : uint8

.. _function-stbimage_boost_Image_rq_blit_alpha_Image_Image_int_int_int_int_int_int_int_int_int_0x1ce:

.. das:function:: Image.blit_alpha(src: Image; sx: int; sy: int; dx: int; dy: int; w: int; h: int; r: int; g: int; b: int)

def Image.blit_alpha

:Arguments: * **src** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **sx** : int

            * **sy** : int

            * **dx** : int

            * **dy** : int

            * **w** : int

            * **h** : int

            * **r** : int

            * **g** : int

            * **b** : int

.. _function-stbimage_boost_Image_rq_to_channels_Image_int_0x1ea:

.. das:function:: Image.to_channels(target_channels: int) : Image

def Image.to_channels

:Arguments: * **target_channels** : int

.. _function-stbimage_boost_Image_rq_to_bpc_Image_int_0x201:

.. das:function:: Image.to_bpc(target_bpc: int) : Image

def Image.to_bpc

:Arguments: * **target_bpc** : int


++++++++++++++++++
Image construction
++++++++++++++++++

  *  :ref:`make_image (w: int; h: int; channels: int; bpc: int = 1) : Image <function-stbimage_boost_make_image_int_int_int_int>`

.. _function-stbimage_boost_make_image_int_int_int_int:

.. das:function:: make_image(w: int; h: int; channels: int; bpc: int = 1) : Image

Create a blank (zeroed) image with the given dimensions.


:Arguments: * **w** : int

            * **h** : int

            * **channels** : int

            * **bpc** : int


+++++++++++++
Image loading
+++++++++++++

  *  :ref:`image_info (path: string) : tuple\<w:int;h:int;comp:int\> <function-stbimage_boost_image_info_string>`
  *  :ref:`is_16_bit (path: string) : bool <function-stbimage_boost_is_16_bit_string>`
  *  :ref:`is_16_bit_from_memory (data: array\<uint8\>) : bool <function-stbimage_boost_is_16_bit_from_memory_array_ls_uint8_gr_>`
  *  :ref:`is_hdr (path: string) : bool <function-stbimage_boost_is_hdr_string>`
  *  :ref:`is_hdr_from_memory (data: array\<uint8\>) : bool <function-stbimage_boost_is_hdr_from_memory_array_ls_uint8_gr_>`
  *  :ref:`load_image (path: string; var error: string&) : Image <function-stbimage_boost_load_image_string_string_ref_>`
  *  :ref:`load_image (path: string) : Image <function-stbimage_boost_load_image_string>`

.. _function-stbimage_boost_image_info_string:

.. das:function:: image_info(path: string) : tuple<w:int;h:int;comp:int>

Get image dimensions and channel count without loading pixel data.


:Arguments: * **path** : string

.. _function-stbimage_boost_is_16_bit_string:

.. das:function:: is_16_bit(path: string) : bool

Returns true if the file contains 16-bit data.


:Arguments: * **path** : string

.. _function-stbimage_boost_is_16_bit_from_memory_array_ls_uint8_gr_:

.. das:function:: is_16_bit_from_memory(data: array<uint8>) : bool

Returns true if the memory buffer contains 16-bit data.


:Arguments: * **data** : array<uint8>

.. _function-stbimage_boost_is_hdr_string:

.. das:function:: is_hdr(path: string) : bool

Returns true if the file is in HDR format.


:Arguments: * **path** : string

.. _function-stbimage_boost_is_hdr_from_memory_array_ls_uint8_gr_:

.. das:function:: is_hdr_from_memory(data: array<uint8>) : bool

Returns true if the memory buffer contains HDR format data.


:Arguments: * **data** : array<uint8>


load_image
^^^^^^^^^^

.. _function-stbimage_boost_load_image_string_string_ref_:

.. das:function:: load_image(path: string; error: string&) : Image

Load an image from file. Sets ``error`` on failure.


:Arguments: * **path** : string

            * **error** : string\ &

.. _function-stbimage_boost_load_image_string:

.. das:function:: load_image(path: string) : Image


++++++++++++
Pixel access
++++++++++++

  *  :ref:`with_pixels (var self: Image; blk: block\<(var pixels:array\<float\>#):void\>) <function-stbimage_boost_with_pixels_Image_block_ls_var_pixels_c_array_ls_float_gr__hh__c_void_gr_>`
  *  :ref:`with_pixels (var self: Image; blk: block\<(var pixels:array\<uint8\>#):void\>) <function-stbimage_boost_with_pixels_Image_block_ls_var_pixels_c_array_ls_uint8_gr__hh__c_void_gr_>`
  *  :ref:`with_pixels (var self: Image; blk: block\<(var pixels:array\<uint16\>#):void\>) <function-stbimage_boost_with_pixels_Image_block_ls_var_pixels_c_array_ls_uint16_gr__hh__c_void_gr_>`
  *  :ref:`with_pixels_16 (var self: Image; blk: block\<(var pixels:array\<uint16\>#):void\>) <function-stbimage_boost_with_pixels_16_Image_block_ls_var_pixels_c_array_ls_uint16_gr__hh__c_void_gr_>`
  *  :ref:`with_pixels_f (var self: Image; blk: block\<(var pixels:array\<float\>#):void\>) <function-stbimage_boost_with_pixels_f_Image_block_ls_var_pixels_c_array_ls_float_gr__hh__c_void_gr_>`
  *  :ref:`with_row (var self: Image; y: int; blk: block\<(var row:array\<float\>#):void\>) <function-stbimage_boost_with_row_Image_int_block_ls_var_row_c_array_ls_float_gr__hh__c_void_gr_>`
  *  :ref:`with_row (var self: Image; y: int; blk: block\<(var row:array\<uint8\>#):void\>) <function-stbimage_boost_with_row_Image_int_block_ls_var_row_c_array_ls_uint8_gr__hh__c_void_gr_>`
  *  :ref:`with_row (var self: Image; y: int; blk: block\<(var row:array\<uint16\>#):void\>) <function-stbimage_boost_with_row_Image_int_block_ls_var_row_c_array_ls_uint16_gr__hh__c_void_gr_>`
  *  :ref:`with_row_16 (var self: Image; y: int; blk: block\<(var row:array\<uint16\>#):void\>) <function-stbimage_boost_with_row_16_Image_int_block_ls_var_row_c_array_ls_uint16_gr__hh__c_void_gr_>`
  *  :ref:`with_row_f (var self: Image; y: int; blk: block\<(var row:array\<float\>#):void\>) <function-stbimage_boost_with_row_f_Image_int_block_ls_var_row_c_array_ls_float_gr__hh__c_void_gr_>`


with_pixels
^^^^^^^^^^^

.. _function-stbimage_boost_with_pixels_Image_block_ls_var_pixels_c_array_ls_float_gr__hh__c_void_gr_:

.. das:function:: with_pixels(self: Image; blk: block<(var pixels:array<float>#):void>)

Access pixel data as ``array<float>``. Image must have ``bpc == 4``.


:Arguments: * **self** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **blk** : block<(pixels:array<float>\ #):void>

.. _function-stbimage_boost_with_pixels_Image_block_ls_var_pixels_c_array_ls_uint8_gr__hh__c_void_gr_:

.. das:function:: with_pixels(self: Image; blk: block<(var pixels:array<uint8>#):void>)

.. _function-stbimage_boost_with_pixels_Image_block_ls_var_pixels_c_array_ls_uint16_gr__hh__c_void_gr_:

.. das:function:: with_pixels(self: Image; blk: block<(var pixels:array<uint16>#):void>)

----

.. _function-stbimage_boost_with_pixels_16_Image_block_ls_var_pixels_c_array_ls_uint16_gr__hh__c_void_gr_:

.. das:function:: with_pixels_16(self: Image; blk: block<(var pixels:array<uint16>#):void>)

Explicit-name alias for ``with_pixels`` with uint16 block. For use in generics.


:Arguments: * **self** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **blk** : block<(pixels:array<uint16>\ #):void>

.. _function-stbimage_boost_with_pixels_f_Image_block_ls_var_pixels_c_array_ls_float_gr__hh__c_void_gr_:

.. das:function:: with_pixels_f(self: Image; blk: block<(var pixels:array<float>#):void>)

Explicit-name alias for ``with_pixels`` with float block. For use in generics.


:Arguments: * **self** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **blk** : block<(pixels:array<float>\ #):void>


with_row
^^^^^^^^

.. _function-stbimage_boost_with_row_Image_int_block_ls_var_row_c_array_ls_float_gr__hh__c_void_gr_:

.. das:function:: with_row(self: Image; y: int; blk: block<(var row:array<float>#):void>)

Access a single row as ``array<float>``. Image must have ``bpc == 4``.


:Arguments: * **self** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **y** : int

            * **blk** : block<(row:array<float>\ #):void>

.. _function-stbimage_boost_with_row_Image_int_block_ls_var_row_c_array_ls_uint8_gr__hh__c_void_gr_:

.. das:function:: with_row(self: Image; y: int; blk: block<(var row:array<uint8>#):void>)

.. _function-stbimage_boost_with_row_Image_int_block_ls_var_row_c_array_ls_uint16_gr__hh__c_void_gr_:

.. das:function:: with_row(self: Image; y: int; blk: block<(var row:array<uint16>#):void>)

----

.. _function-stbimage_boost_with_row_16_Image_int_block_ls_var_row_c_array_ls_uint16_gr__hh__c_void_gr_:

.. das:function:: with_row_16(self: Image; y: int; blk: block<(var row:array<uint16>#):void>)

Explicit-name alias for ``with_row`` with uint16 block.


:Arguments: * **self** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **y** : int

            * **blk** : block<(row:array<uint16>\ #):void>

.. _function-stbimage_boost_with_row_f_Image_int_block_ls_var_row_c_array_ls_float_gr__hh__c_void_gr_:

.. das:function:: with_row_f(self: Image; y: int; blk: block<(var row:array<float>#):void>)

Explicit-name alias for ``with_row`` with float block.


:Arguments: * **self** :  :ref:`Image <struct-stbimage_boost-Image>`

            * **y** : int

            * **blk** : block<(row:array<float>\ #):void>


++++++++++++++++
Image properties
++++++++++++++++