Module Overview

class pyora.Project
add_group(path, z_index='above', offsets=(0, 0), opacity=1.0, visible=True, composite_op='svg:src-over', uuid=None, isolated=True, **kwargs)

Append a new layer group to the project

The group added this way starts out with no children (empty)

Parameters:
  • path (str) – Absolute filesystem-like path of the group in the project. For example “/group1” or “/group1/group2”. If given without a leading slash, like “group3”, we assume the group is placed at the root of the project.
  • z_index (str, int) – the index to place the new layer in inside of the group. ‘above’ places the layer at the top of the group. ‘below’ places the layer at the very bottom of the group. Other numbers (1 indexed) place the layer at that z_index, similar to css z-indices.
  • offsets (tuple[int]) – tuple of (x, y) offset (in px) from the top-left corner of the Canvas
  • opacity (float) – group opacity 0.0 to 1.0
  • visible (bool) – is the group visible (hidden if false)
  • composite_op (str) – composite operation attribute passed directly to stack / layer element (see blend modes documentation)
  • uuid (str) – uuid identifier value for this group
  • isolation (bool) – Is the group isolated (composited separately from the groups below it)
Returns:

reference to the newly created group layer object
Return type:

pyora.Layer
add_layer(image, path=None, z_index='above', offsets=(0, 0), opacity=1.0, visible=True, composite_op='svg:src-over', uuid=None, **kwargs)

Append a new layer to the project

Parameters:
  • image (PIL.Image()) – a PIL Image() object containing the image data to add
  • path (str) – Absolute filesystem-like path of the group in the project. For example “/group1” or “/group1/group2”. If given without a leading slash, like “group3”, we assume the group is placed at the root of the project.
  • z_index (str, int) – the index to place the new layer in inside of the group. ‘above’ places the layer at the top of the group. ‘below’ places the layer at the very bottom of the group. Other numbers (1 indexed) place the layer at that z_index, similar to css z-indices.
  • offsets (tuple[int]) – tuple of (x, y) offset (in px) from the top-left corner of the Canvas
  • opacity (float) – group opacity 0.0 to 1.0
  • visible (bool) – is the group visible (hidden if false)
  • composite_op (str) – composite operation attribute passed directly to stack / layer element (see blend modes documentation)
  • uuid (str) – uuid identifier value for this group
Returns:

reference to the newly created layer object
Return type:

pyora.Layer
dimensions

Get Project (width, height) dimensions in px

Returns:(width, height) of project, in px
Return type:tuple[int]
static extract_composite(path_or_file, pil=False)

Efficiently extract just existing composite full resolution image in the ORA file

This method extracts just the image data of the thumbnail, without reading the entire ORA file

Parameters:
  • path_or_file (str, File-Like object) – filesystem path or .read()-able file object of ORA file to load
  • pil (bool) – for consistency, if true, wrap the image with PIL and return PIL.Image() object
Returns:

Depends on ‘pil’ argument
Return type:

Bytes or PIL.Image()
static extract_layer(path_or_file, path=None, uuid=None, pil=False)

Efficiently extract just one specific layer image

This method extracts just the image data of the thumbnail, without reading the entire ORA file. Specify either a path or uuid, not both.

Parameters:
  • path_or_file (str, File-Like object) – filesystem path or .read()-able file object of ORA file to load
  • path (str) – Path of layer to extract in the ORA file
  • uuid (str) – uuid of layer to search for in the ORA file (if path not provided)
  • pil (bool) – for consistency, if true, wrap the image with PIL and return PIL.Image() object
Returns:

Depends on ‘pil’ argument
Return type:

Bytes or PIL.Image()
static extract_thumbnail(path_or_file, pil=False)

Efficiently extract just the thumbnail image

This method extracts just the image data of the thumbnail, without reading the entire ORA file

Parameters:
  • path_or_file (str, File-Like object) – filesystem path or .read()-able file object of ORA file to load
  • pil (bool) – for consistency, if true, wrap the image with PIL and return PIL.Image() object
Returns:

Depends on ‘pil’ argument
Return type:

Bytes or PIL.Image()
from_stack_xml(xml_dom, srcs_to_files)

Overwrite the current pyora project instance directly from XML stack + image data sources

This is the minimum amount of data needed to create an ORA project, if perhaps storing ORA files is not as convenient for your use case.

Parameters:
  • xml_dom (str, ET) – either a string of xml or the parsed XML elementtree instance
  • srcs_to_files (dict) – dict of layer “src” attribute strings, to .read()-able File-like objects of of the layer PNG (or other image) data. Any images that PIL supports are fine.
get_by_path(path)

Find a group or layer object using a *Nix-like ‘path’, based on the names of project groups / layers

Paths look like ‘/group1/layer2’, note that while this provides good ability to extract any specific layer in most circumstances, it does not work well in the case that there are multiple groups / layers in the same group, with the same name. In this case, you will need to drill down by using .children(), or alternatively getting by uuid with get_by_uuid()

Returns:the found layer object
Return type:pyora.Group or pyora.Layer
get_image_data(use_original=False)

Get a PIL Image() object of the entire project (composite)

Parameters:use_original (bool) – If true, and If there was a stored ‘mergedimage’ already in the file which was opened, just return that. In any other case a new merged image is generated.
Returns:Image object
Return type:PIL Image()
get_stack_xml()

Get the current stack xml representation of the project

Can be saved for later use with Project.set_stack_xml(), equivalent to the ‘stack.xml’ which would be saved on Project.save()

Returns:string of stack xml
Return type:str
get_thumbnail_image_data(use_original=False)

Get the thumbnail image for the ora file

Get PIL Image() object, composite, resized to standard 256x256 max ORA thumbnail size.

Parameters:use_original (bool) – If true, and If there was a stored ‘mergedimage’ already in the file which was opened, just return that. In any other case a new merged image is generated.
Returns:Image object
Return type:PIL Image()
static load(path_or_file)

Load an existing ORA file into a pyora project

Factory function. will instantiate and return a new pyora.Project() when called.

Parameters:path_or_file (str, File-Like object) – filesystem path or .read()-able file object of ORA file to load
Returns:the new instance
Return type:pyora.Project
move(src_uuid, dst_uuid, dst_z_index='above')

Reposition a layer or group

Move some layer or group and all of its children somewhere else inside the project If there are some layer groups that are missing for the destination to exist, they will be created automatically.

Parameters:
  • uuid (str) – source group/layer uuid to move
  • dest_uuid (str) – dest group uuid to place source element inside of
  • dest_z_index (str, int) – the index to place the new layer in inside of the group. ‘above’ places the layer at the top of the group. ‘below’ places the layer at the very bottom of the group. Other numbers (1 indexed) place the layer at that z_index, similar to css z-indices
static new(width, height, xres=72, yres=72)

Start a blank new ORA project

Factory function. will instantiate and return a new pyora.Project() when called.

Parameters:
  • width (int) – initial width of canvas, in px
  • height (int) – initial height of canvas, in px
  • xres (int) – nominal resolution pixels per inch in x
  • yres (int) – nominal resolution pixels per inch in y
Returns:

the new instance
Return type:

pyora.Project
remove(uuid)

Remove a layer or group

Parameters:uuid (str) – The UUID of the layer or group to remove
root

Get a reference to the outermost layer group containing everything else

Returns:root Group() Object
Return type:pyora.Group
save(path_or_file, composite_image=None, use_original=False)

Save the current project state to an ORA file.

Parameters:
  • path (str) – path to the ora file to save
  • composite_image (PIL.Image()) – PIL Image() object of the composite rendered canvas. It is used to create the mergedimage full rendered preview, as well as the thumbnail image. If not provided, one will be generated by pyora’s Render() class by stacking all of the layers in the project. Note that the image you pass may be modified during this process, so if you need to use it elsewhere in your code, you should copy() first.
  • use_original (bool) – If true, and If there was a stored ‘mergedimage’ already in the file which was opened, use that for the ‘mergedimage’ in the new file, instead of rendering a new one.
set_stack_xml(xml_dom, new_sources=None)

Set the current stack xml representation of the project

Using the ‘stack.xml’ standard format, update the current project to reflect the new scheme. This allows updating attributes / positioning in an exportable format without needing to store / transfer all of the data in the raster files themselves. Important! all uuids in the incoming scheme must match uuids in the current project, or undefined behavior fill occur.

Parameters:
  • xml_dom (str, ET()) – String or parsed elementtree() of the stack.xml standard format
  • new_sources (dict) – (optional) dict of {uuid: new Image() object} of raster image sources to update during application of the new xml stack
class pyora.Layer(image, project, elem)
dimensions

Not a supported ORA spec metadata, but we can read the specific PNG data to obtain the dimension value

Returns:(width, height) tuple of dimensions based on the content rect
Return type:tuple[int]
get_image_data(raw=True)

Get a PIL Image() object of the layer.

By default the returned image will always be the same dimension as the project canvas, and the original image data will be placed / cropped inside of that.

Parameters:raw (bool) – If True, Instead of cropping to canvas, just get the image data exactly as it exists
Returns:image data
Return type:PIL Image()
name

the layer name

Type:Returns
Type:str
set_image_data(image)

Change the image data for this layer

Parameters:image (PIL.Image()) – pil Image() object of the new layer data
z_index_global

Get the stacking position of the layer, relative to the entire canvas. Higher numbers are ‘on top’ of lower numbers. The lowest value is 1.

Returns:the z_index of the layer
Return type:int
class pyora.Group(project, elem)
children

Returns all layers and groups under this group

children_recursive

Returns all layers and groups under this group, and groups under that, etc.

dimensions

Not a supported ORA spec metadata, but we can read all png data below us to find the total enclosed size

get_image_data(raw=True)

Get a PIL Image() object of the group (composed of all underlying layers).

groups

Returns the group objects under this group

isolated

bool - is the layer rendered isolated

Type:return
layers

Returns the layer objects under this group

name

the layer name

Type:Returns
Type:str
uuids

Returns the uuids belonging to all layers and groups under this group

class pyora.Renderer(project)
render(root_group=None)

Perform the full project render over the current project

Parameters:root_group (pyora.Group) – optional, instead of starting with the outermost group of the project, render just the specified group and its children
Returns:The fully composited image
Return type:PIL.Image