core.frame

`pyctools.core.frame.Frame`	Container for a single image or frame of video.
`pyctools.core.frame.Metadata`	Store "data about the data" in a `Frame`.

class Frame(**kwds)[source]

Bases: object

Container for a single image or frame of video.

This is a fairly free-form container (to which you can add other data), but every Frame object must have:

a frame number
a data item
a type description string, such as “RGB”
a Metadata item

The data item can be a numpy.ndarray or PIL.Image object. In most instances a numpy.ndarray should have 3 dimensions: line, pixel, colour component.

initialise(other)[source]

Initialise a Frame from another Frame.

Copies the metadata and (a reference to) the data from other. Note that the data is not actually copied – you must make a copy of the data before changing it.

Parameters:: other (Frame) – The frame to copy.

set_audit(*args, **kwds)[source]: See Metadata.set_audit.

merge_audit(*args, **kwds)[source]: See Metadata.merge_audit.

size()[source]: Return image dimensions (height, width)

as_numpy(dtype=None, copy=False)[source]

Get image data in numpy.ndarray form.

Note that if the image data is already in the correct format this can be a null operation.

When converting to limited range types (numpy.uint8, numpy.uint16) the data is clipped (limited) to the range.

Parameters:

dtype (numpy.dtype) – What dtype the data should be in, e.g. numpy.float32. If dtype is None then no conversion will be done.
copy (bool) – Forces a copy of the data to be made, even if it is already an numpy.ndarray with the requested dtype.

Returns:

The image data as numpy.ndarray.

Return type:

numpy.ndarray

as_PIL()[source]

Get image data in PIL.Image form.

Note that if the image data is already in the correct format this is a null operation.

Returns:: The image data as PIL.Image.
Return type:: PIL.Image

class Metadata(**kwds)[source]

Bases: object

Store “data about the data” in a Frame.

This container stores information about an image or video sequence that is not the actual image data. The main use of this is the “audit trail”. Each Pyctools component extends the audit trail with a short description of what it does, creating a detailed record of the processing. This can be useful in working out what went wrong (or right!) in some cases.

Many image file formats (such as JPEG) allow storage of metadata within the image file, but in Pyctools the metadata is always stored in a separate “sidecar” file. This allows the use of any image/video file format and, because the metadata is stored in XMP text format, the sidecar can be read with any text editor.

“Raw” video files, often used to store YUV, have their image dimensions and “fourcc” format stored in a metadata file. The pyctools-setmetadata tool can be used to create or modify the metadata file if this information is missing.

set_audit(component, text, with_history=True, with_date=False, with_config=None)[source]

Set audit trail.

This is a convenient way to add to the audit trail in a “standard” format. The component’s module and class names are added to the audit trail to record which component did the processing. The text should describe what was done and finish with a newline, e.g. data = FFT(data)\n. Using the word data to describe single input or output data keeps the audit trail consistent. If you are combining two or more inputs you can “rename” each one with the merge_audit method.

Parameters:

component (Component) – The component that’s processing the frame.
text (str) – Text to be added to the audit trail.
with_history (bool) – Whether to include the previous audit trail.
with_date (bool) – Whether to include the current date & time in the audit trail. This is primarily used when writing files.
with_config (ConfigParent) – Whether to add the component’s configuration options with config.ConfigParent.audit_string.

merge_audit(parts)[source]

Merge audit trails from two or more frames.

The audit trail from each frame is indented and wrapped with braces ({}). This makes the audit trail easier to read when a component uses two or more inputs.

The parts parameter is a dict of Frame or Metadata objects. The dict keys are used to label each indented audit trail.

For example, this Python code:

out_frame.merge_audit({'Y': Y_frame, 'UV': UV_frame})
out_frame.set_audit(
    self, 'data = YUVtoRGB(Y, UV)\n    matrix: {}\n'.format(matrix))

could produce this audit trail:

Y = {
    data = test.y
        path: '/home/jim/Videos/test.y', looping: 'repeat', noaudit: True
        <pyctools.components.io.videofilereader.VideoFileReader>
    }
UV = {
    data = test.uv
        path: '/home/jim/Videos/test.uv', looping: 'repeat', noaudit: True
        <pyctools.components.io.videofilereader.VideoFileReader>
    }
data = YUVtoRGB(Y, UV)
    matrix: 601
    <pyctools.components.colourspace.yuvtorgb.YUVtoRGB>

Parameters:: parts (dict) – The inputs to merge.

from_file(path)[source]

Read metadata from an XMP sidecar file or, if there is no sidecar, from the image/video file (if it has metadata).

Returns the Metadata object, allowing convenient code like this:

md = Metadata().from_file(path)

Parameters:: path (str) – The image/video file path name.
Return type:: Metadata

to_file(path, thumbnail=None)[source]

Write metadata to an image, video or XMP sidecar file.

Parameters:: path (str) – The image/video file path name.

copy(other)[source]

Copy metadata from another Metadata object.

Returns the Metadata object, allowing convenient code like this:

md = Metadata().copy(other_md)

Parameters:: other (Metadata) – The metadata to copy.
Return type:: Metadata

image_size()[source]

Get image dimensions from metadata.

This is primarily used by the RawFileReader component, as raw video files don’t have a header in which to store the dimensions.

Returns:: width, height.
Return type:: int, int

get(tag, default=None)[source]

Get a metadata value.

Each metadata value is referenced by a tag – a short string such as 'xlen' or 'audit'. In the sidecar file these tag names are prepended with 'Xmp.pyctools.', which corresponds to a custom namespace in the XML file.

Parameters:: tag (str) – The tag name.
Returns:: The metadata value associated with tag.
Return type:: str

set(tag, value)[source]

Set a metadata value.

Each metadata value is referenced by a tag – a short string such as 'xlen' or 'audit'. In the sidecar file these tag names are prepended with 'Xmp.pyctools.', which corresponds to a custom namespace in the XML file.

Parameters:

tag (str) – The tag name.
value (str) – The metadata value.

Comments or questions? Please email jim@jim-easterbrook.me.uk.