add flags support

see #229
libvips · Jan 22, 2024 · 85affa5 · 85affa5
1 parent bbeef60
commit 85affa5
Show file tree

Hide file tree

Showing 7 changed files with 151 additions and 35 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,8 @@ All notable changes to `:vips` will be documented in this file.
 ## master
 
 - added `animate-image.php` example [jcupitt]
+- added flags support [jcupitt]
+- added `keep.php` example [jcupitt]
 
 ## 2.3.0 - 2023-09-26
 

diff --git a/examples/fields.php b/examples/fields.php
@@ -5,16 +5,21 @@
 
 use Jcupitt\Vips;
 
-$im = Vips\Image::newFromFile($argv[1]);
-
-$names = $im->getFields();
-
-echo "$argv[1]\n";
-foreach ($names as &$name) {
-    $value = $im->get($name);
-    echo "$name: $value\n";
+function printMetadata($im)
+{
+    foreach ($im->getFields() as &$name) {
+        $value = $im->get($name);
+        if (str_ends_with($name, "-data")) {
+            $len = strlen($value);
+            $value = "<$len bytes of binary data>";
+        }
+        echo "   $name: $value\n";
+    }
 }
 
+$im = Vips\Image::newFromFile($argv[1]);
+printMetadata($im);
+
 /*
  * Local variables:
  * tab-width: 4

diff --git a/examples/generate_phpdoc.py b/examples/generate_phpdoc.py
@@ -1,12 +1,12 @@
 #!/usr/bin/python3
 
+# needs pyvips 2.2.3 or later
+
 from pyvips import Image, Introspect, GValue, Error, \
-    ffi, values_for_enum, vips_lib, gobject_lib, \
+    ffi, enum_dict, flags_dict, vips_lib, gobject_lib, \
     type_map, type_name, type_from_name, nickname_find
 
 # This file generates the phpdoc comments for the magic methods and properties.
-# It's in Python, since we use the whole of FFI, not just the
-# small bit exposed by php-vips-ext.
 
 # Regenerate docs with something like:
 #
@@ -292,6 +292,10 @@ def add_enum(gtype, a, b):
 
     type_map(type_from_name('GEnum'), add_enum)
 
+    # Filter internal enums
+    blacklist = ['VipsImageType', 'VipsToken']
+    all_enums = [name for name in all_enums if name not in blacklist]
+
     for name in all_enums:
         gtype = type_from_name(name)
         php_name = remove_prefix(name)
@@ -310,14 +314,59 @@ def add_enum(gtype, a, b):
             f.write('abstract class {0}\n'.format(php_name))
             f.write('{\n')
 
-            for value in values_for_enum(gtype):
-                php_name = value.replace('-', '_').upper()
+            for key, value in enum_dict(gtype).items():
+                php_name = key.replace('-', '_').upper()
+                if php_name in reserved_php_names:
+                    php_name = reserved_php_names[php_name]
+                f.write('    const {0} = \'{1}\';\n'.format(php_name, key))
+
+            f.write('}\n')
+
+
+def generate_flags():
+    all_flags = []
+
+    def add_flags(gtype, a, b):
+        nickname = type_name(gtype)
+        all_flags.append(nickname)
+
+        type_map(gtype, add_flags)
+
+        return ffi.NULL
+
+    type_map(type_from_name('GFlags'), add_flags)
+
+    # Filter internal flags
+    blacklist = ['VipsForeignFlags']
+    all_flags = [name for name in all_flags if name not in blacklist]
+
+    for name in all_flags:
+        gtype = type_from_name(name)
+        php_name = remove_prefix(name)
+
+        print('Generating {0}.php ...'.format(php_name))
+
+        with open('{0}.php'.format(php_name), 'w') as f:
+            f.write(preamble)
+            f.write('\n')
+            f.write('namespace Jcupitt\\Vips;\n')
+            f.write('\n')
+            f.write('/**\n')
+            f.write(' * The {0} flags.\n'.format(php_name))
+            f.write(class_header)
+            f.write(' */\n')
+            f.write('abstract class {0}\n'.format(php_name))
+            f.write('{\n')
+
+            for key, value in flags_dict(gtype).items():
+                php_name = key.replace('-', '_').upper()
                 if php_name in reserved_php_names:
                     php_name = reserved_php_names[php_name]
-                f.write('    const {0} = \'{1}\';\n'.format(php_name, value))
+                f.write('    const {0} = {1};\n'.format(php_name, value))
 
             f.write('}\n')
 
 
 generate_auto_doc('ImageAutodoc.php')
 generate_enums()
+generate_flags()
diff --git a/examples/keep.php b/examples/keep.php
@@ -0,0 +1,41 @@
+#!/usr/bin/env php
+<?php
+
+require dirname(__DIR__) . '/vendor/autoload.php';
+
+use Jcupitt\Vips;
+
+function printMetadata($im)
+{
+    foreach ($im->getFields() as &$name) {
+        $value = $im->get($name);
+        if (str_ends_with($name, "-data")) {
+            $len = strlen($value);
+            $value = "<$len bytes of binary data>";
+        }
+        echo "   $name: $value\n";
+    }
+}
+
+$im = Vips\Image::newFromFile($argv[1]);
+echo "$argv[1]\n";
+printMetadata($im);
+
+echo "\nafter keep => icc\n";
+$buf = $im->tiffsave_buffer(['keep' => Vips\ForeignKeep::ICC]);
+$im2 = Vips\Image::newFromBuffer($buf, "");
+printMetadata($im2);
+
+echo "\nafter keep => exif|xmp\n";
+$buf = $im->tiffsave_buffer(['keep' => Vips\ForeignKeep::ICC | Vips\ForeignKeep::XMP]);
+$im2 = Vips\Image::newFromBuffer($buf, "");
+printMetadata($im2);
+
+/*
+ * Local variables:
+ * tab-width: 4
+ * c-basic-offset: 4
+ * End:
+ * vim600: expandtab sw=4 ts=4 fdm=marker
+ * vim<600: expandtab sw=4 ts=4
+ */
diff --git a/src/ImageType.php → src/ForeignKeep.php b/src/ImageType.php → src/ForeignKeep.php
@@ -39,22 +39,21 @@
 namespace Jcupitt\Vips;
 
 /**
- * The ImageType enum.
+ * The ForeignKeep flags.
  * @category  Images
  * @package   Jcupitt\Vips
  * @author    John Cupitt <[email protected]>
  * @copyright 2016 John Cupitt
  * @license   https://opensource.org/licenses/MIT MIT
  * @link      https://github.com/jcupitt/php-vips
  */
-abstract class ImageType
+abstract class ForeignKeep
 {
-    const ERROR = 'error';
-    const NONE = 'none';
-    const SETBUF = 'setbuf';
-    const SETBUF_FOREIGN = 'setbuf-foreign';
-    const OPENIN = 'openin';
-    const MMAPIN = 'mmapin';
-    const MMAPINRW = 'mmapinrw';
-    const OPENOUT = 'openout';
+    const NONE = 0;
+    const EXIF = 1;
+    const XMP = 2;
+    const IPTC = 4;
+    const ICC = 8;
+    const OTHER = 16;
+    const ALL = 31;
 }
diff --git a/src/Token.php → src/ForeignPngFilter.php b/src/Token.php → src/ForeignPngFilter.php
@@ -39,18 +39,20 @@
 namespace Jcupitt\Vips;
 
 /**
- * The Token enum.
+ * The ForeignPngFilter flags.
  * @category  Images
  * @package   Jcupitt\Vips
  * @author    John Cupitt <[email protected]>
  * @copyright 2016 John Cupitt
  * @license   https://opensource.org/licenses/MIT MIT
  * @link      https://github.com/jcupitt/php-vips
  */
-abstract class Token
+abstract class ForeignPngFilter
 {
-    const LEFT = 'left';
-    const RIGHT = 'right';
-    const STRING = 'string';
-    const EQUALS = 'equals';
+    const NONE = 8;
+    const SUB = 16;
+    const UP = 32;
+    const AVG = 64;
+    const PAETH = 128;
+    const ALL = 248;
 }
diff --git a/src/ImageAutodoc.php b/src/ImageAutodoc.php
@@ -160,7 +160,7 @@
  *     @throws Exception
  * @method Image convi(Image $mask, array $options = []) Int convolution operation.
  *     @throws Exception
- * @method Image convsep(Image $mask, array $options = []) Seperable convolution operation.
+ * @method Image convsep(Image $mask, array $options = []) Separable convolution operation.
  *     @throws Exception
  * @method Image copy(array $options = []) Copy an image.
  *     @throws Exception
@@ -372,6 +372,18 @@
  *     @throws Exception
  * @method void jxlsave_target(Target $target, array $options = []) Save image in JPEG-XL format.
  *     @throws Exception
+ * @method static Image kakaduload(string $filename, array $options = []) Load JPEG2000 image.
+ *     @throws Exception
+ * @method static Image kakaduload_buffer(string $buffer, array $options = []) Load JPEG2000 image.
+ *     @throws Exception
+ * @method static Image kakaduload_source(Source $source, array $options = []) Load JPEG2000 image.
+ *     @throws Exception
+ * @method void kakadusave(string $filename, array $options = []) Save image in JPEG2000 format.
+ *     @throws Exception
+ * @method string kakadusave_buffer(array $options = []) Save image in JPEG2000 format.
+ *     @throws Exception
+ * @method void kakadusave_target(Target $target, array $options = []) Save image in JPEG2000 format.
+ *     @throws Exception
  * @method Image labelregions(array $options = []) Label regions in an image.
  *     @throws Exception
  * @method Image linear(float[]|float $a, float[]|float $b, array $options = []) Calculate (a * in + b).
@@ -380,9 +392,9 @@
  *     @throws Exception
  * @method static Image logmat(float $sigma, float $min_ampl, array $options = []) Make a Laplacian of Gaussian image.
  *     @throws Exception
- * @method static Image magickload(string $filename, array $options = []) Load file with ImageMagick7.
+ * @method static Image magickload(string $filename, array $options = []) Load file with ImageMagick.
  *     @throws Exception
- * @method static Image magickload_buffer(string $buffer, array $options = []) Load buffer with ImageMagick7.
+ * @method static Image magickload_buffer(string $buffer, array $options = []) Load buffer with ImageMagick.
  *     @throws Exception
  * @method void magicksave(string $filename, array $options = []) Save file with ImageMagick.
  *     @throws Exception
@@ -457,6 +469,12 @@
  *     @throws Exception
  * @method Image msb(array $options = []) Pick most-significant byte from an image.
  *     @throws Exception
+ * @method static Image niftiload(string $filename, array $options = []) Load NIfTI volume.
+ *     @throws Exception
+ * @method static Image niftiload_source(Source $source, array $options = []) Load NIfTI volumes.
+ *     @throws Exception
+ * @method void niftisave(string $filename, array $options = []) Save image to nifti file.
+ *     @throws Exception
  * @method static Image openexrload(string $filename, array $options = []) Load an OpenEXR image.
  *     @throws Exception
  * @method static Image openslideload(string $filename, array $options = []) Load file with OpenSlide.
@@ -481,9 +499,9 @@
  *     @throws Exception
  * @method static Image pngload_source(Source $source, array $options = []) Load png from source.
  *     @throws Exception
- * @method void pngsave(string $filename, array $options = []) Save image to file as PNG.
+ * @method void pngsave(string $filename, array $options = []) Save image to png file.
  *     @throws Exception
- * @method string pngsave_buffer(array $options = []) Save image to buffer as PNG.
+ * @method string pngsave_buffer(array $options = []) Save image to png buffer.
  *     @throws Exception
  * @method void pngsave_target(Target $target, array $options = []) Save image to target as PNG.
  *     @throws Exception