def get(self, name):
"""Get an item of metadata.
Fetches an item of metadata as a Python value. For example::
orientation = image.get('orientation')
would fetch the image orientation.
Args:
name (str): The name of the piece of metadata to get.
Returns:
The metadata item as a Python value.
Raises:
:class:`.Error`
"""
# with old libvips, we must fetch properties (as opposed to
# metadata) via VipsObject
if not at_least_libvips(8, 5):
gtype = super(Image, self).get_typeof(name)
if gtype != 0:
return super(Image, self).get(name)
gv = GValue()
result = vips_lib.vips_image_get(self.pointer, _to_bytes(name),
gv.pointer)
if result != 0:
raise Error('unable to get {0}'.format(name))
return gv.get()
def new_from_memory(data, width, height, bands, format):
"""Wrap an image around a memory array.
Wraps an Image around an area of memory containing a C-style array. For
example, if the ``data`` memory array contains four bytes with the
values 1, 2, 3, 4, you can make a one-band, 2x2 uchar image from
it like this::
image = Image.new_from_memory(data, 2, 2, 1, 'uchar')
A reference is kept to the data object, so it will not be
garbage-collected until the returned image is garbage-collected.
This method is useful for efficiently transferring images from PIL or
NumPy into libvips.
See :meth:`.write_to_memory` for the opposite operation.
Use :meth:`.copy` to set other image attributes.
Args:
data (bytes): A memoryview or buffer object.
width (int): Image width in pixels.
height (int): Image height in pixels.
bands (int): Number of bands.
format (BandFormat): Band format.
Returns:
A new :class:`Image`.
Raises:
:class:`.Error`
"""
format_value = GValue.to_enum(GValue.format_type, format)
pointer = ffi.from_buffer(data)
# py3:
# - memoryview has .nbytes for number of bytes in object
# - len() returns number of elements in top array
# py2:
# - buffer has no nbytes member
# - but len() gives number of bytes in object
nbytes = data.nbytes if hasattr(data, 'nbytes') else len(data)
vi = vips_lib.vips_image_new_from_memory(pointer,
nbytes,
width, height, bands,
format_value)
if vi == ffi.NULL:
raise Error('unable to make image from memory')
image = pyvips.Image(vi)
# keep a secret ref to the underlying object .. this reference will be
# inherited by things that in turn depend on us, so the memory we are
# using will not be freed
image._references.append(data)
return image
def composite(self, other, mode, **kwargs):
"""Composite a set of images with a set of modes."""
if not isinstance(other, list):
other = [other]
if not isinstance(mode, list):
mode = [mode]
# modes are VipsBlendMode enums, but we have to pass as array of int --
# we need to map str->int by hand
mode = [GValue.to_enum(GValue.blend_mode_type, x) for x in mode]
return pyvips.Operation.call('composite', [self] + other, mode,
**kwargs)
def new_from_memory(data, width, height, bands, format):
"""Wrap an image around a memory array.
Wraps an Image around an area of memory containing a C-style array. For
example, if the ``data`` memory array contains four bytes with the
values 1, 2, 3, 4, you can make a one-band, 2x2 uchar image from
it like this::
image = Image.new_from_memory(data, 2, 2, 1, 'uchar')
A reference is kept to the data object, so it will not be
garbage-collected until the returned image is garbage-collected.
This method is useful for efficiently transferring images from PIL or
NumPy into libvips.
See :meth:`.write_to_memory` for the opposite operation.
Use :meth:`.copy` to set other image attributes.
Args:
data (bytes): A memoryview or buffer object.
width (int): Image width in pixels.
height (int): Image height in pixels.
format (BandFormat): Band format.
Returns:
A new :class:`Image`.
Raises:
:class:`.Error`
"""
format_value = GValue.to_enum(GValue.format_type, format)
vi = vips_lib.vips_image_new_from_memory(ffi.from_buffer(data),
len(data),
width, height, bands,
format_value)
if vi == ffi.NULL:
raise Error('unable to make image from memory')
image = pyvips.Image(vi)
# keep a secret ref to the underlying object
image._data = data
return image
def set_type(self, gtype, name, value):
"""Set the type and value of an item of metadata.
Sets the type and value of an item of metadata. Any old item of the
same name is removed. See :class:`GValue` for types.
Args:
gtype (int): The GType of the metadata item to create.
name (str): The name of the piece of metadata to create.
value (mixed): The value to set as a Python value. It is
converted to the ``gtype``, if possible.
Returns:
None
Raises:
None
"""
gv = GValue()
gv.set_type(gtype)
gv.set(value)
vips_lib.vips_image_set(self.pointer, _to_bytes(name), gv.pointer)
def generate_sphinx(operation_name):
"""Make a sphinx-style docstring.
This is used to generate the off-line docs.
"""
op = Operation.new_from_name(operation_name)
if (op.get_flags() & _OPERATION_DEPRECATED) != 0:
raise Error('No such operator.',
'operator "{0}" is deprecated'.format(operation_name))
# we are only interested in non-deprecated args
args = [[name, flags] for name, flags in op.get_args()
if not flags & _DEPRECATED]
# find the first required input image arg, if any ... that will be self
member_x = None
for name, flags in args:
if ((flags & _INPUT) != 0 and (flags & _REQUIRED) != 0
and op.get_typeof(name) == GValue.image_type):
member_x = name
break
required_input = [
name for name, flags in args if (flags & _INPUT) != 0 and
(flags & _REQUIRED) != 0 and name != member_x
]
optional_input = [
name for name, flags in args
if (flags & _INPUT) != 0 and (flags & _REQUIRED) == 0
]
required_output = [
name for name, flags in args
if ((flags & _OUTPUT) != 0 and (flags & _REQUIRED) != 0) or (
(flags & _INPUT) != 0 and (flags & _REQUIRED) != 0 and
(flags & _MODIFY) != 0)
]
optional_output = [
name for name, flags in args
if (flags & _OUTPUT) != 0 and (flags & _REQUIRED) == 0
]
if member_x is not None:
result = '.. method:: '
else:
result = '.. staticmethod:: '
args = []
args += required_input
args += [
x + ' = ' + GValue.gtype_to_python(op.get_typeof(x))
for x in optional_input
]
args += [x + ' = bool' for x in optional_output]
result += operation_name + '(' + ", ".join(args) + ')\n\n'
description = op.get_description()
result += description[0].upper() + description[1:] + '.\n\n'
result += 'Example:\n'
result += ' ' + ', '.join(required_output) + ' = '
if member_x is not None:
result += member_x + "." + operation_name + '('
else:
result += 'pyvips.Image.' + operation_name + '('
result += ', '.join(required_input)
if len(optional_input) > 0 and len(required_input) > 0:
result += ', '
result += ', '.join([
x + ' = ' + GValue.gtype_to_python(op.get_typeof(x))
for x in optional_input
])
result += ')\n\n'
for name in required_input + optional_input:
result += (':param {0} {1}: {2}\n'.format(
GValue.gtype_to_python(op.get_typeof(name)), name,
op.get_blurb(name)))
for name in optional_output:
result += (':param bool {0}: enable output: {1}\n'.format(
name, op.get_blurb(name)))
output_types = [
GValue.gtype_to_python(op.get_typeof(name))
for name in required_output
]
if len(output_types) == 1:
output_type = output_types[0]
else:
output_type = 'list[' + ', '.join(output_types) + ']'
if len(optional_output) > 0:
output_types += ['Dict[str, mixed]']
output_type += ' or list[' + ', '.join(output_types) + ']'
result += ':rtype: ' + output_type + '\n'
result += ':raises Error:\n'
return result
def argstr(name):
return (u' {0} ({1}): {2}\n'.format(
name, GValue.gtype_to_python(op.get_typeof(name)),
op.get_blurb(name)))
def generate_docstring(operation_name):
"""Make a google-style docstring.
This is used to generate help() output.
"""
if operation_name in Operation._docstring_cache:
return Operation._docstring_cache[operation_name]
op = Operation.new_from_name(operation_name)
if (op.get_flags() & _OPERATION_DEPRECATED) != 0:
raise Error('No such operator.',
'operator "{0}" is deprecated'.format(operation_name))
# we are only interested in non-deprecated args
args = [[name, flags] for name, flags in op.get_args()
if not flags & _DEPRECATED]
# find the first required input image arg, if any ... that will be self
member_x = None
for name, flags in args:
if ((flags & _INPUT) != 0 and (flags & _REQUIRED) != 0
and op.get_typeof(name) == GValue.image_type):
member_x = name
break
required_input = [
name for name, flags in args if (flags & _INPUT) != 0 and
(flags & _REQUIRED) != 0 and name != member_x
]
optional_input = [
name for name, flags in args
if (flags & _INPUT) != 0 and (flags & _REQUIRED) == 0
]
required_output = [
name for name, flags in args
if ((flags & _OUTPUT) != 0 and (flags & _REQUIRED) != 0) or (
(flags & _INPUT) != 0 and (flags & _REQUIRED) != 0 and
(flags & _MODIFY) != 0)
]
optional_output = [
name for name, flags in args
if (flags & _OUTPUT) != 0 and (flags & _REQUIRED) == 0
]
description = op.get_description()
result = description[0].upper() + description[1:] + ".\n\n"
result += "Example:\n"
result += " " + ", ".join(required_output) + " = "
if member_x is not None:
result += member_x + "." + operation_name + "("
else:
result += "pyvips.Image." + operation_name + "("
result += ", ".join(required_input)
if len(optional_input) > 0 and len(required_input) > 0:
result += ", "
result += ", ".join([
x + " = " + GValue.gtype_to_python(op.get_typeof(x))
for x in optional_input
])
result += ")\n"
def argstr(name):
return (u' {0} ({1}): {2}\n'.format(
name, GValue.gtype_to_python(op.get_typeof(name)),
op.get_blurb(name)))
result += "\nReturns:\n"
for name in required_output:
result += argstr(name)
names = []
if member_x is not None:
names += [member_x]
names += required_input
result += "\nArgs:\n"
for name in names:
result += argstr(name)
if len(optional_input) > 0:
result += "\nKeyword args:\n"
for name in optional_input:
result += argstr(name)
if len(optional_output) > 0:
result += "\nOther Parameters:\n"
for name in optional_output:
result += argstr(name)
result += "\nRaises:\n :class:`.Error`\n"
# add to cache to save building again
Operation._docstring_cache[operation_name] = result
return result
def generate_sphinx(operation_name):
"""Make a sphinx-style docstring.
This is used to generate the off-line docs.
"""
intro = Introspect.get(operation_name)
if (intro.flags & _OPERATION_DEPRECATED) != 0:
raise Error('No such operator.',
'operator "{0}" is deprecated'.format(operation_name))
if intro.member_x is not None:
result = '.. method:: '
else:
result = '.. staticmethod:: '
args = []
args += intro.method_args
args += [
x + '=' + GValue.gtype_to_python(intro.details[x]['type'])
for x in intro.optional_input
]
args += [x + '=bool' for x in intro.optional_output]
result += operation_name + '(' + ", ".join(args) + ')\n\n'
result += intro.description[0].upper() + \
intro.description[1:] + '.\n\n'
result += 'Example:\n'
result += ' ' + ', '.join(intro.required_output) + ' = '
if intro.member_x is not None:
result += intro.member_x + "." + operation_name + '('
else:
result += 'pyvips.Image.' + operation_name + '('
args = []
args += intro.method_args
args += [
x + '=' + GValue.gtype_to_python(intro.details[x]['type'])
for x in intro.optional_input
]
result += ', '.join(args)
result += ')\n\n'
for name in intro.method_args + intro.optional_input:
details = intro.details[name]
result += (':param {0}: {1}\n'.format(name, details['blurb']))
result += (':type {0}: {1}\n'.format(
name, GValue.gtype_to_python(details['type'])))
for name in intro.optional_output:
result += (':param {0}: enable output: {1}\n'.format(
name, intro.details[name]['blurb']))
result += (':type {0}: bool\n'.format(name))
output_types = [
GValue.gtype_to_python(intro.details[name]['type'])
for name in intro.required_output
]
if len(output_types) == 1:
output_type = output_types[0]
else:
output_type = 'list[' + ', '.join(output_types) + ']'
if len(intro.optional_output) > 0:
output_types += ['Dict[str, mixed]']
output_type += ' or list[' + ', '.join(output_types) + ']'
result += ':rtype: ' + output_type + '\n'
result += ':raises Error:\n'
return result
def argstr(name):
details = intro.details[name]
return (u' {0} ({1}): {2}\n'.format(
name, GValue.gtype_to_python(details['type']),
details['blurb']))
def generate_docstring(operation_name):
"""Make a google-style docstring.
This is used to generate help() output.
"""
# we cache these to save regeneration
if operation_name in Operation._docstring_cache:
return Operation._docstring_cache[operation_name]
intro = Introspect.get(operation_name)
if (intro.flags & _OPERATION_DEPRECATED) != 0:
raise Error('No such operator.',
'operator "{0}" is deprecated'.format(operation_name))
result = intro.description[0].upper() + intro.description[1:] + '.\n\n'
result += 'Example:\n'
result += ' ' + ', '.join(intro.required_output) + ' = '
if intro.member_x is not None:
result += intro.member_x + '.' + operation_name + '('
else:
result += 'pyvips.Image.' + operation_name + '('
args = []
args += intro.method_args
args += [
x + '=' + GValue.gtype_to_python(intro.details[x]['type'])
for x in intro.optional_input
]
args += [x + '=bool' for x in intro.optional_output]
result += ", ".join(args) + ')\n'
def argstr(name):
details = intro.details[name]
return (u' {0} ({1}): {2}\n'.format(
name, GValue.gtype_to_python(details['type']),
details['blurb']))
result += '\nReturns:\n'
for name in intro.required_output:
result += argstr(name)
result += '\nArgs:\n'
if intro.member_x is not None:
result += argstr(intro.member_x)
for name in intro.method_args:
result += argstr(name)
if len(intro.optional_input) > 0:
result += '\nKeyword args:\n'
for name in intro.optional_input:
result += argstr(name)
if len(intro.optional_output) > 0:
result += '\nOther Parameters:\n'
for name in intro.optional_output:
result += argstr(name)
result += '\nRaises:\n :class:`.Error`\n'
# add to cache to save building again
Operation._docstring_cache[operation_name] = result
return result
