Class BitonalBitmapOperations

Class BitonalBitmapOperations#

Class Documentation#

class BitonalBitmapOperations#

Utility functions for working with 1‑bit‑per‑pixel (bitonal) bitmaps.

This class contains static helpers to read, write, and bulk-edit bitonal images that implement libCZI::IBitonalBitmapData. It provides overloads that:

  • Accept IBitonalBitmapData* or std::shared_ptr<IBitonalBitmapData> and manage Lock/Unlock internally via ScopedBitonalBitmapLocker.

  • Accept a pre-acquired BitonalBitmapLockInfo plus the bitmap extent for zero-overhead operations where the caller controls the lock lifetime.

Provided operations:

  • GetPixelValue(…) - read a single pixel.

  • SetPixelValue(…) - write a single pixel.

  • Fill(…) - fill a rectangular ROI; the ROI is clipped to the bitmap extent.

  • SetAllPixels(…) - set all pixels to a uniform value.

  • CopyAt(…) - masked copy from a source bitmap to a destination bitmap; only pixels for which the mask bit is set are copied, starting at the given destination offset. Regions outside the destination are ignored.

Locking and thread-safety:

  • Pointer/shared_ptr overloads perform Lock/Unlock internally and are safe to call even when other threads also lock the same bitmap (IBitonalBitmapData permits multiple locks).

  • LockInfo overloads assume the caller holds a valid lock for the duration of the call. When writing, ensure exclusive access to avoid data races.

Memory layout:

  • Pixels are packed at 1 bit per pixel in scanlines separated by stride bytes.

  • Callers should not depend on the bit ordering within each byte; use these helpers instead of decoding bits directly.

Coordinates and clipping:

  • x and y are 0-based. All operations clip to [0, width) x [0, height).

Example: 

// Clear an ROI and then set one pixel
libCZI::IntRect roi{10, 20, 32, 8};
libCZI::BitonalBitmapOperations::Fill(bitonal.get(), roi, false);
libCZI::BitonalBitmapOperations::SetPixelValue(bitonal.get(), 12, 22, true);

// High-performance path with a pre-acquired lock
libCZI::ScopedBitonalBitmapLockerSP lock{ bitonal };
libCZI::BitonalBitmapOperations::Fill(lock, bitonal->GetSize(), roi, true);

// Masked copy into destination at (100, 50)
libCZI::BitonalBitmapOperations::CopyAt(src.get(), mask.get(),
    libCZI::IntPoint{100, 50}, dst.get());

Public Static Functions

static inline bool GetPixelValue(const std::shared_ptr<IBitonalBitmapData> &bmData, std::uint32_t x, std::uint32_t y)#

Gets the value of a specific pixel in a bitonal bitmap.

This overload locks and unlocks the bitmap internally.

Parameters:

  • bmData – The bitonal bitmap.

  • x – The x-coordinate of the pixel (0-based).

  • y – The y-coordinate of the pixel (0-based).

Returns:

The value of the pixel (true for set/1, false for clear/0).

static bool GetPixelValue(const BitonalBitmapLockInfo &lock_info, const libCZI::IntSize &extent, std::uint32_t x, std::uint32_t y)#

Gets the value of a specific pixel in a locked bitonal bitmap.

Parameters:

  • lock_info – Information describing the locked bitonal bitmap data (ptrData points to the first scanline; stride is in bytes).

  • extent – The bitmap extent (width/height).

  • x – The x-coordinate of the pixel (0-based).

  • y – The y-coordinate of the pixel (0-based).

Returns:

The value of the pixel (true for set/1, false for clear/0).

static inline bool GetPixelValue(const IBitonalBitmapData *bitonal_bitmap, const BitonalBitmapLockInfo &lock_info, std::uint32_t x, std::uint32_t y)#

Gets the value of a specific pixel in a locked bitonal bitmap.

Convenience overload when the extent can be taken from the bitmap.

Parameters:

  • bitonal_bitmap – The bitonal bitmap the lock was acquired from.

  • lock_info – The lock information corresponding to bitonal_bitmap.

  • x – The x-coordinate of the pixel (0-based).

  • y – The y-coordinate of the pixel (0-based).

Returns:

The value of the pixel (true for set/1, false for clear/0).

static inline void SetPixelValue(IBitonalBitmapData *bitonal_bitmap_data, std::uint32_t x, std::uint32_t y, bool value)#

Sets the value of a specific pixel in a bitonal bitmap.

This overload locks and unlocks the bitmap internally.

Parameters:

  • bitonal_bitmap_data – The bitonal bitmap to modify.

  • x – The x-coordinate of the pixel (0-based).

  • y – The y-coordinate of the pixel (0-based).

  • value – The value to write (true for set/1, false for clear/0).

static inline void SetPixelValue(const std::shared_ptr<IBitonalBitmapData> &bitonal_bitmap_data, std::uint32_t x, std::uint32_t y, bool value)#

Sets the value of a specific pixel in a bitonal bitmap.

This overload locks and unlocks the bitmap internally.

Parameters:

  • bitonal_bitmap_data – The bitonal bitmap to modify (shared_ptr).

  • x – The x-coordinate of the pixel (0-based).

  • y – The y-coordinate of the pixel (0-based).

  • value – The value to write (true for set/1, false for clear/0).

static void SetPixelValue(const BitonalBitmapLockInfo &lock_info, const libCZI::IntSize &extent, std::uint32_t x, std::uint32_t y, bool value)#

Sets the value of a specific pixel in a locked bitonal bitmap.

Parameters:

  • lock_info – Information describing the locked bitonal bitmap data.

  • extent – The bitmap extent (width/height).

  • x – The x-coordinate of the pixel (0-based).

  • y – The y-coordinate of the pixel (0-based).

  • value – The value to write (true for set/1, false for clear/0).

static inline void Fill(IBitonalBitmapData *bitonal_bitmap_data, const libCZI::IntRect &rect, bool value)#

Fills a rectangular region of interest (ROI) in a bitonal bitmap with a specified value.

This overload locks and unlocks the bitmap internally.

Parameters:

  • bitonal_bitmap_data – The bitonal bitmap to modify.

  • rect – The rectangle to fill. The ROI is clipped to the bitmap extent.

  • value – The value to fill the ROI with (true for set/1, false for clear/0).

static inline void Fill(const std::shared_ptr<IBitonalBitmapData> &bitonal_bitmap_data, const libCZI::IntRect &rect, bool value)#

Fills a rectangular region of interest (ROI) in a bitonal bitmap with a specified value.

This overload locks and unlocks the bitmap internally.

Parameters:

  • bitonal_bitmap_data – The bitonal bitmap to modify.

  • rect – The rectangle to fill. The ROI is clipped to the bitmap extent.

  • value – The value to fill the ROI with (true for set/1, false for clear/0).

static void Fill(const BitonalBitmapLockInfo &lock_info, const libCZI::IntSize &extent, const libCZI::IntRect &roi, bool value)#

Fills a rectangular region of interest (ROI) in a bitonal bitmap with a specified value.

Parameters:

  • lock_info – Information describing the locked bitonal bitmap data.

  • extent – The extent of the bitonal bitmap.

  • roi – The region of interest to fill. The ROI is clipped to the bitmap extent.

  • value – The value to fill the ROI with.

static inline void SetAllPixels(const std::shared_ptr<IBitonalBitmapData> &bitonal_bitmap_data, bool value)#

Sets all pixels in the bitonal bitmap to a uniform value.

This overload locks and unlocks the bitmap internally.

Parameters:

  • bitonal_bitmap_data – The bitonal bitmap to modify (shared_ptr).

  • value – The value to assign to every pixel (true for set/1, false for clear/0).

static inline void SetAllPixels(IBitonalBitmapData *bitonal_bitmap_data, bool value)#

Sets all pixels in the bitonal bitmap to a uniform value.

This overload locks and unlocks the bitmap internally.

Parameters:

  • bitonal_bitmap_data – The bitonal bitmap to modify.

  • value – The value to assign to every pixel (true for set/1, false for clear/0).

static void SetAllPixels(const BitonalBitmapLockInfo &lock_info, const libCZI::IntSize &extent, bool value)#

Sets all pixels in a locked bitonal bitmap to a uniform value.

Parameters:

  • lock_info – Information describing the locked bitonal bitmap data.

  • extent – The bitmap extent (width/height).

  • value – The value to assign to every pixel (true for set/1, false for clear/0).

static void CopyAt(libCZI::IBitmapData *source_bitmap, libCZI::IBitonalBitmapData *mask, const libCZI::IntPoint &offset, libCZI::IBitmapData *destination_bitmap)#

Copies pixels from a source bitmap into a destination bitmap using a bitonal mask.

For every mask pixel that is set (true), the corresponding source pixel is copied to destination at position (offset.x + x, offset.y + y), where (x, y) is the mask/source coordinate. Regions outside any involved extent are ignored.

Preconditions and notes:

  • source_bitmap and destination_bitmap must have the same PixelType and compatible strides.

  • The effective copy area is the intersection of: mask extent shifted by offset, destination extent, and source extent.

  • The function will lock/unlock the involved bitmaps internally as needed.

Parameters:

  • source_bitmap – Source image providing the pixels to copy.

  • mask – Bitonal mask controlling which pixels to copy.

  • offset – Destination offset where mask (0,0) maps to.

  • destination_bitmap – Destination image receiving copied pixels.

static inline std::shared_ptr<libCZI::IBitonalBitmapData> Decimate(int neighborhood_size, libCZI::IBitonalBitmapData *source_bitmap)#

Decimates a bitonal bitmap - every second pixel is discarded in each direction. A pixel is set to 1 in the decimated bitmap if all the pixels in the neighborhood in the source bitmap are set to 1. The neighborhood is specified by the neighborhood_size parameter, and is a square of size (2 x neighborhood_size + 1) x (2 x neighborhood_size + 1) around the pixel in question. The size of the decimated bitmap is half the size of the source bitmap (rounded down).

Parameters:

  • neighborhood_size – Size of the neighborhood - this parameter must be in the range 0 to 7. A value of 0 means only the center pixel is considered, while larger values create a larger square neighborhood for the filtering operation.

  • source_bitmap – [in] The source bitmap.

Returns:

The decimated bitmap.

static std::shared_ptr<libCZI::IBitonalBitmapData> Decimate(int neighborhood_size, const BitonalBitmapLockInfo &lock_info, const libCZI::IntSize &extent)#

Decimates a bitonal bitmap using pre-acquired lock information - every second pixel is discarded in each direction. A pixel is set to 1 in the decimated bitmap if all the pixels in the neighborhood in the source bitmap are set to 1. The neighborhood is specified by the neighborhood_size parameter, and is a square of size (2 x neighborhood_size + 1) x (2 x neighborhood_size + 1) around the pixel in question. The size of the decimated bitmap is half the size of the source bitmap (rounded down).

This overload operates on pre-acquired lock information for optimal performance when the caller already holds a lock on the source bitmap.

Parameters:

  • neighborhood_size – Size of the neighborhood - this parameter must be in the range 0 to 7. A value of 0 means only the center pixel is considered, while larger values create a larger square neighborhood for the filtering operation.

  • lock_info – Information describing the locked bitonal bitmap data of the source bitmap.

  • extent – The extent (width and height) of the source bitmap.

Returns:

A new decimated bitonal bitmap with dimensions (extent.w/2, extent.h/2). The returned bitmap is a newly allocated IBitonalBitmapData object.

Contents