kaolin.visualize.web.io

This module provides general binary encoding utilities, focusing on simple types and encoding of PyTorch tensors for transferring custom messages over the web, for example see . Sister encoding-decoding functions are also available in javascript when using Kaolin’s Plotly Dash integrations (See kaolin.visualize.dash).

Essential

kaolin.visualize.web.io.encode_message(tag, content, binary=True, image_format=ImageFormat.PNG, jpeg_quality=90)

Encodes a tagged message using the standard tag / msg keys.

Parameters

  • tag – tag or message type to set.

  • content – content to set.

  • binary – if True, will be encoded as binary and as JSON otherwise.

  • image_format – ImageFormat (or its string alias 'raw' / 'png' / 'jpeg' / 'jpg'). Defaults to _DEFAULT_IMAGE_FORMAT. Forwarded to to_binary(); only relevant for binary encoding.

  • jpeg_quality – 0..100 quality for JPEG encoding (default _DEFAULT_JPEG_QUALITY). Forwarded to to_binary(); only used when image_format is JPEG.

Returns

bytes (binary=True) or JSON string (binary=False).

kaolin.visualize.web.io.to_binary(value, image_format=ImageFormat.PNG, jpeg_quality=90)

Encodes any message as binary.

Image-encodable detection is uint8-only: only np.ndarray / torch.Tensor of dtype uint8 and a recognized image layout ((H, W), (H, W, C), (C, H, W)) are routed through the PNG / JPEG codec when image_format requests it. Float tensors, integer tensors of other dtypes, batched tensors, and tensors with channel counts the requested codec cannot express are written as raw typed arrays — i.e. unchanged from the 'raw' baseline.

Parameters

  • value – value to encode.

  • image_format – ImageFormat or its string alias ('raw' / 'png' / 'jpeg' / 'jpg'). Defaults to _DEFAULT_IMAGE_FORMAT. 'jpg' is normalized to ImageFormat.JPEG.

  • jpeg_quality – 0..100 quality for JPEG encoding (default _DEFAULT_JPEG_QUALITY); only used when image_format is JPEG.

Returns

Encoded bytes.

kaolin.visualize.web.io.from_binary(bytes_msg: bytes)

Decodes value from binary.

Parameters

bytes_msg –

Returns:

class kaolin.visualize.web.io.BinaryIoDataType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Types supported for binary serialization by the to_binary() and from_binary() functions. Matches window.kaolin.io.BinaryIoDataType enum in Kaolin Javascript API for client-server compatibility.

DICT = 10

Dictionary/Map of named values

FLOAT16 = 6

16-bit floating point, corresponds to torch.float16

FLOAT32 = 7

32-bit floating point, corresponds to torch.float32 and used for regular floats

FLOAT64 = 8

64-bit floating point, corresponds to torch.float64

INT16 = 2

Signed 16-bit integer, corresponds to torch.int16

INT32 = 3

Signed 32-bit integer, corresponds to torch.int32 and used for regular ints

INT64 = 5

Signed 64-bit integer, corresponds to torch.int64

INT8 = 0

Signed 8-bit integer, corresponds to torch.int8

JPEG = 13

JPEG-compressed image; payload is the encoded JPEG byte stream

LIST = 11

List of values

PNG = 12

PNG-compressed image; payload is the encoded PNG byte stream

STRING = 9

UTF-8 encoded string

UINT32 = 4

Unsigned 32-bit integer, corresponds to torch.uint32

UINT8 = 1

Unsigned 8-bit integer, corresponds to torch.uint8

UNSUPPORTED = 100

Unsupported type marker

Other API

There should be no reason to use the lower-level helpers below, but we expose them in case they are helpful. Encoding particular types should be handled using the high-level encoders to_binary() and from_binary().

class kaolin.visualize.web.io.ImageFormat(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Image-encoding mode threaded through encode_message() and to_binary().

Selects how image-shaped uint8 tensors are encoded:

  • RAW — no image detection; tensors are written as raw typed arrays (default; bytes are unchanged from the pre-PNG/JPEG format).

  • PNG — image-shaped uint8 tensors with 1, 3, or 4 channels are compressed as PNG.

  • JPEG — image-shaped uint8 tensors with 1 or 3 channels are compressed as JPEG. 4-channel tensors fall through to the raw uint8 path (JPEG cannot express alpha).

JPEG = 'jpeg'
PNG = 'png'
RAW = 'raw'
classmethod coerce(value)

Accepts an ImageFormat, None, or a string 'raw', 'png', 'jpeg', 'jpg' (case-insensitive). Returns the canonical enum member or raises ValueError.

kaolin.visualize.web.io.convert_value_to_supported_format(value)
kaolin.visualize.web.io.gap_until_offset_4(current_offset: int) → int
kaolin.visualize.web.io.gap_until_offset_n(current_offset: int, n: int) → int

Calculate the gap needed to align current_offset to a multiple of n. Arrays such as Int32Array cannot start at offsets that are not a multiple of 4. This helps us find the right offset.

Parameters

  • current_offset – Current byte offset

  • n – Alignment requirement (e.g., 4 for 4-byte alignment)

Returns

Number of bytes to add to reach proper alignment

kaolin.visualize.web.io.int32_to_binary(single_int)
kaolin.visualize.web.io.named_value_from_binary(bytes_msg, offset)
kaolin.visualize.web.io.named_value_to_binary(name, value, initial_offset=0, image_format=ImageFormat.PNG, jpeg_quality=90)
kaolin.visualize.web.io.np_type_from_type_id(type_id)

Returns NumPy dtype and bytes per element for given type ID.

Parameters

type_id – Binary I/O data type ID

Returns

(numpy_dtype, bytes_per_element) or (None, 0) if unknown

Return type

tuple

kaolin.visualize.web.io.string_from_binary(bytes_msg, offset, byte_length)

Decodes UTF-8 string of specified length from binary data.

Parameters

  • bytes_msg – Input binary data (bytes)

  • offset – Byte offset in data

  • byte_length – String length in bytes

Returns

Decoded string

kaolin.visualize.web.io.string_to_binary(string)

Encodes string to binary data using UTF-8 encoding.

Parameters

string – String to encode

Returns

bytes containing UTF-8 encoded bytes

kaolin.visualize.web.io.typed_value_from_binary(bytes_msg, offset, length, type_code)
kaolin.visualize.web.io.value_from_binary(bytes_msg, offset)
kaolin.visualize.web.io.value_to_binary(in_value, initial_offset=0, image_format=ImageFormat.PNG, jpeg_quality=90)

Encodes a single value to binary, prepending the wire metadata header.

Image-encodable detection is uint8-only: only np.ndarray / torch.Tensor of dtype uint8 are considered for PNG / JPEG encoding when image_format requests it. Every other path (floats, non-uint8 ints, tensors with shapes that don’t look like an image, JPEG-incompatible 4-channel inputs) is byte-identical to the 'raw' baseline.

kaolin.visualize.web.io.value_to_type(converted_value, image_format)

Maps an already-convert_value_to_supported_format()-ed value to its BinaryIoDataType.

image_format selects whether image-shaped uint8 ndarrays are reported as BinaryIoDataType.PNG / JPEG (and therefore routed through the codec by value_to_binary()), or as plain UINT8 arrays.