snip.snippets.image.ImageSnip¶

class snip.snippets.image.ImageSnip(image: Image, **kwargs)¶

Image snip class.

Represents an image in the labbook. You may construct an image from a matplotlib figure, a PIL image, or a numpy array.

The default constructor is not meant to be used directly. Instead, use the from_array, from_pil, or from_matplotlib constructors.

Attributes

`book_id`	The identifier of the book the snippet belongs to
`deployment`	The deployment URL of the snippet
`bounding_box`	Bounding box of the snippet on a page.
`height`	Return the height of the image.
`mirror`	Mirror the snippet on the x axis.
`pos`	Position of the snippet on a page.
`rotation`	Rotation of the snippet on a page in degrees.
`schema`	Schema to validate the snippet.
`size`	Return the width and height of the image.
`type`	The type identifier of the snippet e.g. 'text', 'image' etc.
`width`	Return the width of the image.
`x`	Vertical position of the snippet.
`y`	Horizontal position of the snippet.

Methods

`__init__`(image, **kwargs)	Create an image snip from a PIL image.
`as_json`([validate])	Return the snippet as a dictionary in basic snippet json format.
`from_array`(array[, mode])	Create an image snip from a numpy array.
`from_matplotlib`(figure[, savefig_kwargs])	Create an image snip from a matplotlib figure.
`from_path`(path, **kwargs)	Create an image snip from a file path.
`from_pil`(image, **kwargs)	Create an image snip from a PIL image.
`preview`([token])	Generate a snippet preview.
`scale`(ratio)	Scale the image by a given ratio.
`set_height`(height[, keep_ratio])	Set the height of the image.
`set_width`(width[, keep_ratio])	Set the width of the image.
`upload`([book_id, token, validate])	Upload the snippet to the labbook.

__init__(image: Image, **kwargs)¶

Create an image snip from a PIL image.

Parameters:

image (Image.Image) – The image to display.
kwargs (Any) – Additional keyword arguments passed snip.snippets.base.BaseSnip.__init__.

as_json(validate=True) → dict¶

Return the snippet as a dictionary in basic snippet json format.

Returns a dict in the basic snippet structure.

{
    "book_id": 123
    "type": "text"
    "data": {}
    "view": {}
}

If the schema is set in the class it is used to validate the snippet data before returning it.

Parameters:: validate (bool, optional) – If True, the snippet is validated against the schema. Defaults to True.
Raises:: jsonschema.ValidationError – If the snippet does not match the schema.

book_id: int | None¶: The identifier of the book the snippet belongs to

property bounding_box: Tuple[float, float, float, float]¶

Bounding box of the snippet on a page.

This is the actual size of the snippet on the page, including potential rotation and mirroring.

Returns:: The left, top, right, bottom coordinates of the snippet.
Return type:: Tuple[float, float, float, float]

deployment: str | None¶: The deployment URL of the snippet

classmethod from_array(array, mode: str | None = None, **kwargs) → ImageSnip¶

Create an image snip from a numpy array.

Parameters:

array (Any) – The numpy 3d array to display. The array should be in the format (height, width, 3) or (height, width, 4). See pillow.Image.fromarray for more information on the supported array formats.
mode (Optional[str]) – Optional mode to use when reading obj. Will be determined from type if None.
kwargs (Any) – Additional keyword arguments passed snip.snippets.base.BaseSnip.__init__.

Returns:

The image snip.

Return type:

ImageSnip

classmethod from_matplotlib(figure: Figure, savefig_kwargs: dict | None = None, **kwargs) → ImageSnip¶

Create an image snip from a matplotlib figure.

Parameters:

figure (matplotlib.figure.Figure) – The figure to display.
savefig_kwargs (Optional[dict]) – Optional keyword arguments to pass to figure.savefig.
kwargs (Any) – Additional keyword arguments passed snip.snippets.base.BaseSnip.__init__.

Returns:

The image snip.

Return type:

ImageSnip

classmethod from_path(path: str, **kwargs) → ImageSnip¶

Create an image snip from a file path.

Parameters:

path (str) – The path to the image file.
kwargs (Any) – Additional keyword arguments passed snip.snippets.base.BaseSnip.__init__.

Returns:

The image snip.

Return type:

ImageSnip

classmethod from_pil(image: Image, **kwargs) → ImageSnip¶

Create an image snip from a PIL image.

Parameters:

image (Image.Image) – The image to display.
kwargs (Any) – Additional keyword arguments passed snip.snippets.base.BaseSnip.__init__.

Returns:

The image snip.

Return type:

ImageSnip

property height¶: Return the height of the image.

property mirror¶: Mirror the snippet on the x axis.

property pos: Tuple[float, float] | None¶

Position of the snippet on a page.

Returns none if the position is not set yet.

preview(token: Token | None = None, **kwargs) → Image | None¶

Generate a snippet preview.

This requests a server side rendering of the snippet and returns the preview image.

Returns:

token (Token) – The token to use for the request. If None, the token gets inferred if possible.
**kwargs (Any) – Additional keyword arguments to pass to the requests function.

property rotation¶

Rotation of the snippet on a page in degrees.

The rotation origin is the center of the snippet and is defined in degrees.

scale(ratio: float)¶: Scale the image by a given ratio.

property schema: dict | None¶

Schema to validate the snippet.

The schema is used to validate the snippet and should be a valid jsonschema.Draft202012Validator schema.

Returns:: The schema for this snippet class if available. If none is available, None is returned and the schema functionality is disabled.
Return type:: schema

set_height(height: int, keep_ratio: bool = True)¶: Set the height of the image.

set_width(width: int, keep_ratio: bool = True)¶: Set the width of the image.

property size: Tuple[float, float]¶: Return the width and height of the image.

type: str = 'image'¶: The type identifier of the snippet e.g. ‘text’, ‘image’ etc.

upload(book_id: int | None = None, token: BookToken | None = None, validate=True, **kwargs)¶

Upload the snippet to the labbook.

This method uploads this snippet to a labbok given the snippets book_id and deployment url.

If no token is provided, the token is inferred from the book_id and deployment.

Parameters:

book_id (int, optional) – The book_id of the snippet. Defaults to None. If None, the snippet book_id is derived
token (Token) – The token to use for the request. If None, the token gets inferred if possible.
validate (bool, optional) – Weather to validate the snippet before uploading. Defaults to True.
**kwargs (Any) – Additional keyword arguments to pass to the requests function.

property width¶: Return the width of the image.

property x¶

Vertical position of the snippet.

Returns none if the position is not set yet.

property y¶

Horizontal position of the snippet.

Returns none if the position is not set yet.