CvtColor

Functions for converting image color.

OS	Build Status
Ubuntu 20.04
macOS 11

Installation

If available in Hex, the package can be installed by adding cvt_color to your list of dependencies in mix.exs:

def deps do
  [
    {:cvt_color, "~> 0.1.3"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/cvt_color.

Usage

bgr565_data = CvtColor.cvt(binary_data, :bgr888, :bgr565)

If you have OpenMP enabled, see more details about this in the Optional Config section below.

chunk_size = 65536
bgr565_data = CvtColor.cvt(binary_data, :bgr888, :bgr565, chunk_size)

# to balance the task
# set chunk_size to 0 or do not pass anything
bgr565_data = CvtColor.cvt(binary_data, :bgr888, :bgr565, 0)
bgr565_data = CvtColor.cvt(binary_data, :bgr888, :bgr565)

Currently supported pairs:

Each component in bgr666 and rgb666 takes 8bit space, but only bits in MSB(7-2) are valid.

 MSB 7                                       LSB
┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐
│  X  │  X  │  X  │  X  │  X  │  X  │  -  │  -  │
└─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

X indicates valid bit. - indicates ignored bit.

An example of :rgb666_compact is shown below. Each rectangle indicates 1 bit.

┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
│R5│R4│R3│R2│R1│R0│G5│G4│G3│G2│G1│G0│B5│B4│B3│B2│B1│B0│
└──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘

Optional Config

OpenMP

This project can set to use OpenMP to accelerate the converting process. By default, this project will try to find and use OpenMP. However, you can completely disable OpenMP by setting the environment variable CVT_COLOR_USE_OPENMP to OFF.

Chunk size (when OpenMP is enabled)

When assigning computing task to each thread, cvt_color will try to balance the number of consecutive pixels for each thread. For example, say you have 4 (logical) cores (and didn't set an explicit value for OMP_NUM_THREADS, i.e., OMP_NUM_THREADS will be equal to the number of logical cores), and 4_000_000 pixels, then core 0 will process pixels from index 0 to 999_999, pixels from 1_000_000 to 1_999_999 will be assigned to core 1, and so on. The chunk size is calculated in the way of the following pseudocode:

if not specified chunk_size
    chunk_size = number_of_pixels / ${OMP_NUM_THREADS};
    if chunk_size is 0
        # the result of the integer division is 0
        # which means that number_of_pixels < ${OMP_NUM_THREADS}
        # then a single thread is good enough
        # unless ${OMP_NUM_THREADS} is really a large value
        # e.g., ${OMP_NUM_THREADS} > 1_000_000 or even larger
        chunk_size = number_of_pixels
    endif
endif

However, when you have a relatively fewer number of pixels, say 255, then the time of starting ~${OMP_NUM_THREADS} new threads and waiting for them to finish can take a significant portion of the converting process. Therefore, we should set a minimal chunk size, i.e., the forth argument of CvtColor.cvt_color/4.

The appropriate minimal chunk size can vary a lot depending on the processor (cache size, speed, etc), the threading library (how long it takes to init a new thread).

You can test and find a good value on your device using the benchmark program. To compile the benchmark program, set the environment variable CVT_COLOR_BUILD_BENCHMARK to ON.

Or you can pass different values to CvtColor.cvt_color/4 and pick the one that satisfies your requirement.

The default chunk size is 1048576 (pixels) based on some benchmarks (see below). And presumably, as long as it is a power of 2 and range from 65536 to 1048576, it should be good. But if you are in doubt, you can always run the benchmark on your device to find a good value.

Benchmarks

Image size 7680x4320, pixel format RGB888. The time of generating the source image is not counted, and the source image will only be generated once per benchmark (i.e, per entry in the table below). The converting task will be repeated for 100 times, and the final results denote the average running time per converting.

Note that RGB888 to RGB666 is basically memcpy. RGB666C. in the table below means convert to :rgb666_compact.

chunk_size is the number of pixels (instead of bytes) assigned to a thread.

Time unit is milliseconds.