update to 3.1

- new libvips 8.18 docs
- fix doc generation
- fix warning for new copy arg to __array__
- add a note on PDF load missing in bundled binary
- add gainmap support
- version bump to 3.1

Author: jcupitt

CHANGELOG.rst

@@ -1,6 +1,8 @@
-## Version 3.0.1 (git master)
+## Version 3.1.0 (released 8 December 2025)
 
 - fix glib DLL name with Conan [boussaffawalid]
+- update docs for libvips 8.18 [jcupitt]
+- add `get_gainmap()` [jcupitt]
 
 ## Version 3.0.0 (released 28 April 2025)
 

README.rst

@@ -78,11 +78,12 @@ with:
     $ pip install "pyvips[binary]"
 
 This installs a self-contained package with the most commonly needed
-libraries. It should just work on most common platforms, including Linux,
-Windows and macOS, with x64 and ARM CPUs.
+libraries. It should just work on most platforms, including Linux,
+Windows and macOS, with 64 and 32 bit x64 and ARM CPUs. Note that this libvips
+is missing features like PDF load and OpenSlide support.
 
-If your platform is unsupported or the pre-built binary is
-unsuitable, you can install libvips separately instead.
+If your platform is unsupported or the pre-built binary is unsuitable, you
+can install libvips separately instead.
 
 Local installation
 ------------------

doc/conf.py

@@ -64,9 +64,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'3.0'
+version = u'3.1'
 # The full version, including alpha/beta/rc tags.
-release = u'3.0.1'
+release = u'3.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/vimage.rst

@@ -119,9 +119,7 @@ def values_for_enum(gtype):
 
     result = [_to_string(g_enum_class.values[i].value_nick)
               for i in range(g_enum_class.n_values)]
-    # FIXME: remove after https://github.com/libvips/libvips/pull/4520
-    if 'last' in result:
-        result.remove('last')
+
     return result
 
 
@@ -144,8 +142,7 @@ def enum_dict(gtype):
     result = {_to_string(g_enum_class.values[i].value_nick):
               g_enum_class.values[i].value
               for i in range(g_enum_class.n_values)}
-    # FIXME: remove after https://github.com/libvips/libvips/pull/4520
-    result.pop('last', None)
+
     return result
 
 

pyvips/base.py

@@ -222,6 +222,10 @@ class Interpretation(object):
 
     HSV (str): pixels are HSV
 
+    OKLAB (str): pixels are in Oklab colourspace
+
+    OKLCH (str): pixels are in Oklch colourspace
+
     """
 
     ERROR = 'error'
@@ -244,6 +248,8 @@ class Interpretation(object):
     MATRIX = 'matrix'
     SCRGB = 'scrgb'
     HSV = 'hsv'
+    OKLAB = 'oklab'
+    OKLCH = 'oklch'
 
 
 class OperationRelational(object):
@@ -488,6 +494,8 @@ class Access(object):
 
     SEQUENTIAL (str): top-to-bottom reading only, but with a small buffer
 
+    SEQUENTIAL_UNBUFFERED (str): deprecated, use :class:`.enums.Access.SEQUENTIAL` instead
+
     """
 
     RANDOM = 'random'
@@ -843,6 +851,36 @@ class FailOn(object):
     WARNING = 'warning'
 
 
+class ForeignPdfPageBox(object):
+    """ForeignPdfPageBox.
+
+Each page of a PDF document can contain multiple page boxes,
+also known as boundary boxes or print marks.
+
+Each page box defines a region of the complete page that
+should be rendered. The default region is the crop box.
+
+Attributes:
+
+    MEDIA (str): media box
+
+    CROP (str): crop box
+
+    TRIM (str): trim box
+
+    BLEED (str): bleed box
+
+    ART (str): art box
+
+    """
+
+    MEDIA = 'media'
+    CROP = 'crop'
+    TRIM = 'trim'
+    BLEED = 'bleed'
+    ART = 'art'
+
+
 class ForeignPpmFormat(object):
     """ForeignPpmFormat.
 
@@ -949,7 +987,7 @@ class ForeignDzDepth(object):
 class ForeignDzContainer(object):
     """ForeignDzContainer.
 
-How many pyramid layers to create.
+What container format to use.
 
 Attributes:
 
@@ -971,6 +1009,12 @@ class RegionShrink(object):
 
 How to calculate the output pixels when shrinking a 2x2 region.
 
+Images with alpha (see :meth:`.Image.hasalpha`) always shrink with
+:class:`.enums.RegionShrink.MEAN` and pixels scaled by alpha to avoid fringing.
+
+Set the image interpretation to :class:`.enums.Interpretation.MULTIBAND` to
+treat all bands equally.
+
 Attributes:
 
     MEAN (str): use the average
@@ -1223,21 +1267,21 @@ class Kernel(object):
 
 Attributes:
 
-    NEAREST (str): The nearest pixel to the point.
+    NEAREST (str): the nearest pixel to the point
 
-    LINEAR (str): Convolve with a triangle filter.
+    LINEAR (str): convolve with a triangle filter
 
-    CUBIC (str): Convolve with a cubic filter.
+    CUBIC (str): convolve with a cubic filter
 
-    MITCHELL (str): Convolve with a Mitchell kernel.
+    MITCHELL (str): convolve with a Mitchell kernel
 
-    LANCZOS2 (str): Convolve with a two-lobe Lanczos kernel.
+    LANCZOS2 (str): convolve with a two-lobe Lanczos kernel
 
-    LANCZOS3 (str): Convolve with a three-lobe Lanczos kernel.
+    LANCZOS3 (str): convolve with a three-lobe Lanczos kernel
 
-    MKS2013 (str): Convolve with Magic Kernel Sharp 2013.
+    MKS2013 (str): convolve with Magic Kernel Sharp 2013
 
-    MKS2021 (str): Convolve with Magic Kernel Sharp 2021.
+    MKS2021 (str): convolve with Magic Kernel Sharp 2021
 
     """
 
@@ -1330,7 +1374,9 @@ class ForeignKeep(object):
 
     ICC (int): keep ICC metadata
 
-    OTHER (int): keep other metadata (e.g. PNG comments and some TIFF tags)
+    OTHER (int): keep other metadata (e.g. PNG comments)
+
+    GAINMAP (int): keep the gainmap metadata
 
     ALL (int): keep all metadata
 
@@ -1342,7 +1388,8 @@ class ForeignKeep(object):
     IPTC = 4
     ICC = 8
     OTHER = 16
-    ALL = 31
+    GAINMAP = 32
+    ALL = 63
 
 
 class ForeignPngFilter(object):

pyvips/enums.py

@@ -455,6 +455,12 @@ def cdefs(features):
 
         '''
 
+    if _at_least(features, 8, 18):
+        code += '''
+            VipsImage *vips_image_get_gainmap(VipsImage *image);
+
+        '''
+
     # we must only define these in API mode ... in ABI mode we need to call
     # these things earlier
     if features['api']:

pyvips/vdecls.py

@@ -1,4 +1,4 @@
 # this is used in pyproject.toml and imported into __init__.py
-__version__ = '3.0.1'
+__version__ = '3.1.0'
 
 __all__ = ['__version__']

pyvips/version.py

@@ -982,6 +982,29 @@ def set_kill(self, kill):
 
     # get/set metadata
 
+    def get_gainmap(self, name):
+        """Get the image gainmap, if any.
+
+        Get the gainmap associated with this image, or None for no gainmap.
+        After updating the gainmap, use :meth:`.set_type` to update the
+        `"gainmap"` metadata item.
+
+        Returns:
+            The gainmap image.
+
+        Raises:
+            None
+
+        """
+        if not at_least_libvips(8, 18):
+            return None
+        else:
+            pointer = vips_lib.vips_image_get_gainmap(self.pointer)
+            if pointer == ffi.NULL:
+                return None
+            else:
+                return pyvips.Image(pointer)
+
     def get_typeof(self, name):
         """Get the GType of an item of metadata.
 
@@ -1182,13 +1205,15 @@ def tolist(self):
     #
     #     return interface
 
-    def __array__(self, dtype=None):
+    def __array__(self, dtype=None, copy=None):
         """Conversion to a NumPy array.
 
         Args:
             dtype (str or numpy dtype, optional) The dtype to use for the
                 numpy array. If None, the default dtype of the image is used
                 as defined the global `FORMAT_TO_TYPESTR` dictionary.
+            copy (bool, optional) If True, always copy the data; if None, copy
+                if required; if False, never copy.
 
         Returns:
             numpy.ndarray: The array representation of the image.
@@ -1208,6 +1233,10 @@ def __array__(self, dtype=None):
         """
         import numpy as np
 
+        # we always generate a new image, so if copy is False, we can't work
+        if not copy:
+            raise ValueError
+
         arr = (
             np.frombuffer(self.write_to_memory(),
                           dtype=FORMAT_TO_TYPESTR[self.format])