imgutils.metadata.lsb

This module provides functionality for reading and writing metadata and data using LSB (Least Significant Bit) steganography in images.

Imported from .read:

  • ImageLsbDataExtractor: Class for extracting LSB data from images.

  • LSBExtractor: Class for extracting LSB data from byte arrays.

  • LSBReadError: Exception raised when there’s an error reading LSB data.

  • read_lsb_metadata: Function to read metadata embedded in an image using LSB.

  • read_lsb_raw_bytes: Function to read raw bytes embedded in an image using LSB.

Imported from .write:

  • serialize_pnginfo: Function to serialize PNG metadata.

  • serialize_json: Function to serialize JSON-compatible data.

  • inject_data: Function to inject data into an image using LSB.

  • write_lsb_metadata: Function to write metadata into an image using LSB.

  • write_lsb_raw_bytes: Function to write raw bytes into an image using LSB.

This module combines reading and writing capabilities for LSB steganography, allowing users to embed and extract data or metadata from images seamlessly.

read_lsb_raw_bytes

imgutils.metadata.lsb.read_lsb_raw_bytes(image: str | PathLike | bytes | bytearray | BinaryIO | Image) → bytes[source]

Read raw bytes of LSB-encoded data from an image.

This function loads the image and uses ImageLsbDataExtractor to extract the hidden data.

Parameters:

image (ImageTyping) – The image to extract data from. Can be a file path, URL, or Image object.

Returns:

The extracted raw data.

Return type:

bytes

Raises:

LSBReadError – If there’s an error during the extraction process.

read_lsb_metadata

imgutils.metadata.lsb.read_lsb_metadata(image: str | PathLike | bytes | bytearray | BinaryIO | Image)[source]

Read and decode LSB-encoded metadata from an image.

This function extracts the raw bytes, decompresses them using gzip, and then decodes the result as a JSON object.

Parameters:

image (ImageTyping) – The image to extract metadata from. Can be a file path, URL, or Image object.

Returns:

The decoded metadata as a Python object.

Return type:

dict

Raises:

LSBReadError – If there’s an error during the extraction or decoding process.

write_lsb_raw_bytes

imgutils.metadata.lsb.write_lsb_raw_bytes(image: str | PathLike | bytes | bytearray | BinaryIO | Image, data: bytes | bytearray) → Image[source]

Write raw bytes into an image using LSB steganography.

This function is a wrapper around inject_data that handles image loading.

Parameters:

  • image (ImageTyping) – Input image or path to image

  • data (Union[bytes, bytearray]) – Raw data to be written

Returns:

Image with injected data

Return type:

Image.Image

write_lsb_metadata

imgutils.metadata.lsb.write_lsb_metadata(image: str | PathLike | bytes | bytearray | BinaryIO | Image, data: Any) → Image[source]

Write metadata into an image using LSB steganography.

This function handles different types of metadata, serializing them appropriately before injection into the image.

Parameters:

  • image (ImageTyping) – Input image or path to image

  • data (Any) – Metadata to be written (can be raw bytes, PngInfo, or JSON-serializable data)

Returns:

Image with injected metadata

Return type:

Image.Image

LSBReadError

class imgutils.metadata.lsb.LSBReadError(err: Exception)[source]

Custom exception class for LSB reading errors.

This exception is raised when there’s an error during the LSB data extraction process.

Parameters:

err (Exception) – The original exception that caused the LSB read error.

LSBExtractor

class imgutils.metadata.lsb.LSBExtractor(data: ndarray)[source]

A class for extracting data hidden in the least significant bits of image pixels.

This class provides methods to extract individual bits, bytes, and multi-byte values from image data using LSB steganography techniques.

Parameters:

data (np.ndarray) – The image data as a numpy array.

__init__(data: ndarray)[source]

Initialize the LSBExtractor with image data.

Parameters:

data (np.ndarray) – The image data as a numpy array.

get_next_n_bytes(n)[source]

Extract and return the next n bytes of data.

This method extracts multiple bytes from the image data.

Parameters:

n (int) – The number of bytes to extract.

Returns:

The extracted bytes.

Return type:

bytearray

get_one_byte()[source]

Extract and return one byte of data.

This method extracts 8 bits from the image data to form a single byte.

Returns:

A single byte of extracted data.

Return type:

bytearray

read_32bit_integer()[source]

Extract and return a 32-bit integer from the image data.

This method reads 4 bytes and interprets them as a big-endian 32-bit integer.

Returns:

The extracted 32-bit integer, or None if not enough data is available.

Return type:

int or None

ImageLsbDataExtractor

class imgutils.metadata.lsb.ImageLsbDataExtractor(magic: str = 'stealth_pngcomp')[source]

A class for extracting hidden JSON data from images using LSB steganography.

This class uses the LSBExtractor to read hidden data from an image, expecting a specific magic number and format for the hidden data.

Parameters:

magic (str) – The magic string used to identify the start of the hidden data.

__init__(magic: str = 'stealth_pngcomp')[source]

Initialize the ImageLsbDataExtractor with a magic string.

Parameters:

magic (str) – The magic string used to identify the start of the hidden data.

extract_data(image: Image) → bytes[source]

Extract hidden data from the given image.

This method checks for the magic number, reads the length of the hidden data, and then extracts the data.

Parameters:

image (Image.Image) – The image to extract data from.

Returns:

The extracted raw data.

Return type:

bytes

Raises:

ValueError – If the image is not in RGBA mode or if the magic number doesn’t match.

serialize_pnginfo

imgutils.metadata.lsb.serialize_pnginfo(metadata: PngInfo) → bytes[source]

Serialize PNG metadata into a compressed byte string.

This function extracts metadata from a PngInfo object, converts it to JSON, and then compresses it using gzip.

Parameters:

metadata (PngInfo) – PNG metadata

Returns:

Compressed serialized metadata

Return type:

bytes

serialize_json

imgutils.metadata.lsb.serialize_json(metadata) → bytes[source]

Serialize any JSON-serializable metadata into a compressed byte string.

This function converts the input metadata to JSON and then compresses it using gzip.

Parameters:

metadata (Any) – Metadata to be serialized

Returns:

Compressed serialized metadata

Return type:

bytes

inject_data

imgutils.metadata.lsb.inject_data(image: Image, data: bytes | bytearray) → Image[source]

Inject data into an image using LSB steganography and error correction.

This function embeds the given data into the least significant bits of the image pixels, along with error correction information for robustness.

Parameters:

  • image (Image.Image) – Input image

  • data (Union[bytes, bytearray]) – Data to be injected

Returns:

Image with injected data

Return type:

Image.Image