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