Domain-Specific Types

Rikai provides a suite of domain-specific types that are interoperatable in Spark, Pytorch and Tensorflow.

These domain-specific types implement the following traits.

  • Spark’s User Define Types, allows the types being serialized into Parquet.

  • ToNumpy trait, makes these types automatically converted to appropriate Tensors in Pytorch or Tensorflow.

  • Optionally, Displayable trait, offers native jupyter notebook integration.

  • Optionally, Asset trait, indicates the data being stored externally, and can fetch the data on demand.

Typically, there are convenient spark UDFs (rikai.spark.functions) provided for these types if fit.

Computer Vision

Image contains a reference to the external image. It could be displayed natively in Jupyter notebooks, for example:

_images/image_nb.png
class rikai.types.vision.Image(image: Union[bytes, bytearray, IOBase, str, Path])

An external Image Asset.

It contains a reference URI to an image stored on the remote system.

Parameters

image (bytes, file-like object, str or Path) – It can be the content of image, or a URI / Path of an image.

crop(box: Union[Box2d, List[Box2d]], format: Optional[str] = None) → Union[Image, List[Image]]

Crop image specified by the bounding boxes, and returns the cropped images.

Support crop images in batch, to save I/O overhead to download the original image.

Parameters

  • box (Box2d or List[Box2d]) – The bounding box(es) to crop out of this image.

  • format (str, optional) – The image format to save as

Return type

Image or a list of Image

display(**kwargs)

Custom visualizer for this image in jupyter notebook

Parameters

kwargs (dict) – Optional display arguments

Returns

img

Return type

IPython.display.Image

classmethod from_array(array: ndarray, uri: Optional[Union[str, Path]] = None, mode: Optional[str] = None, format: Optional[str] = None, **kwargs) → Image

Create an image in memory from numpy array.

Parameters

  • array (np.ndarray) – Array data

  • uri (str or Path) – The external URI to store the data.

  • mode (str, optional) – The mode which PIL used to create image. See supported modes on PIL document.

  • format (str, optional) – The image format to save as. See supported formats for details.

  • kwargs (dict, optional) – Optional arguments to pass to PIL.Image.save.

See also

PIL.Image.fromarray, numpy_to_image()

static from_pil(img: PILImage, uri: Optional[Union[str, Path]] = None, format: Optional[str] = None, **kwargs) → Image

Create an image in memory from a PIL.Image.

Parameters

  • img (PIL.Image) – An PIL Image instance

  • uri (str or Path) – The URI to store the image externally.

  • format (str, optional) –

    The image format to save as. See supported formats for details.

  • kwargs (dict, optional) –

    Optional arguments to pass to PIL.Image.save.

static read(uri: Union[str, Path]) → Image

Create an embedded image from external URI

Parameters

uri (str or Path) – The URI pointed to an image.

save(uri: Union[str, Path]) → Image

Save the image into a file, specified by the file path or URI.

Parameters

uri (str or Path) – The external URI to store the image to.

Returns

A new image with the new URI / path

Return type

Image

to_embedded() → Image

Convert this image into an embedded image.

to_numpy() → ndarray

Convert this image into an numpy.ndarray.

to_pil() → PILImage

Return an PIL image.

Note

The caller should close the image. https://pillow.readthedocs.io/en/stable/reference/open_files.html#image-lifecycle

Video

Geometry

class rikai.types.geometry.Box2d(xmin: float, ymin: float, xmax: float, ymax: float)

2-D Bounding Box, defined by (xmin, ymin, xmax, ymax)

xmin

X-coordinate of the top-left point of the box.

Type

float

ymin

Y-coordinate of the top-left point of the box.

Type

float

xmax

X-coordinate of the bottm-right point of the box.

Type

float

ymax

Y-coordinate of the bottm-right point of the box.

Type

float

Example

>>> box = Box2d(1, 2, 3, 4)
>>> box / 2
Box2d(xmin=0.5, ymin=1.0, xmax=1.5, ymax=2.0)
>>> box * (3.5, 5)
Box2d(xmin=3.5, ymin=10.0, xmax=10.5, ymax=20.0)
>>> # Box2d can be used directly with PIL.ImageDraw
>>> draw = PIL.ImageDraw.Draw(img)
>>> draw.rectangle(box, fill="green", width=2)
class rikai.types.geometry.Box3d(center: Point, length: float, width: float, height: float, heading: float)

A 3-D bounding box

center

Center Point of the bounding box

Type

Point

length

The x dimention of the box

Type

float

width

The y dimention of the box

Type

float

height

The z dimention of the box

Type

float

heading

The heading of the bounding box (in radians). The heading is the angle required to rotate +x to the surface normal of the box front face. It is normalized to [-pi, pi).

Type

float

References

class rikai.types.geometry.Point(x: float, y: float, z: float)

Point in a 3-D space, specified by (x, y, z) coordinates.

x

The X coordinate.

Type

float

y

The Y coordinate.

Type

float

z

The Z coordinate.

Type

float