Vips::Image.thumbnail(,width,) constrains to largest dimension and not the width

[da2x]

The second parameter to Image.thumbnail is  documented as a constraint to the width. However, it constrains the largest dimension of the image and not just the width (as the name implies).

Example:

img = Vips::Image.thumbnail("any_800x900_image.png", 600)
img.write_to_file("test.png")

The resulting image is 533x600 px instead of 600x675 px as expected.

[da2x]

The behaviour matches what’s in libvips’ documentation:

The output image will fit within a square of size width x width . You can specify a separate height with the height option.

So the ruby-vips documentation should clarify that width doesn’t just constrain the width but also the hight unless its set to something else.

[jcupitt]

Hello @da2x,

The ruby-vips docs are generated automatically by introspection of the libvips class hierarchy, so it's not easy to edit them, unfortunately.

There's been talk of generating them from the gir file created from the libvips source code (this is how the C docs are built), but no one's got around to it.

It's actually pretty easy -- Vips-8.0.gir:

https://gist.github.com/jcupitt/eef9d24d19d345da6dccbb8e569951c7

Has this for `thumbnail`:

    <function name="thumbnail"
              c:identifier="vips_thumbnail"
              introspectable="0">
      <doc xml:space="preserve"
           filename="resample/thumbnail.c"
           line="1114">Optional arguments:

* @height: %gint, target height in pixels
* @size: #VipsSize, upsize, downsize, both or force
* @no_rotate: %gboolean, don't rotate upright using orientation tag
* @crop: #VipsInteresting, shrink and crop to fill target
* @linear: %gboolean, perform shrink in linear light
* @import_profile: %gchararray, fallback import ICC profile
* @export_profile: %gchararray, export ICC profile
* @intent: #VipsIntent, rendering intent

Make a thumbnail from a file. Shrinking is done in three stages: using any
shrink-on-load features available in the file import library, using a block
shrink, and using a lanczos3 shrink. At least the final 200% is done with
lanczos3. The output should be high quality, and the operation should be
quick.

See vips_thumbnail_buffer() to thumbnail from a memory source.

The output image will fit within a square of size @width x @width. You can
specify a separate height with the @height option.

If you set @crop, then the output image will fill the whole of the @width x
@height rectangle, with any excess cropped away. See vips_smartcrop() for
details on the cropping strategy.

Normally the operation will upsize or downsize as required to fit the image
inside or outside the target size. If @size is set
to #VIPS_SIZE_UP, the operation will only upsize and will just
copy if asked to downsize.
If @size is set
to #VIPS_SIZE_DOWN, the operation will only downsize and will just
copy if asked to upsize.
If @size is #VIPS_SIZE_FORCE, the image aspect ratio will be broken and the
image will be forced to fit the target.

Normally any orientation tags on the input image (such as EXIF tags) are
interpreted to rotate the image upright. If you set @no_rotate to %TRUE,
these tags will not be interpreted.

Shrinking is normally done in sRGB colourspace. Set @linear to shrink in
linear light colourspace instead. This can give better results, but can
also be far slower, since tricks like JPEG shrink-on-load cannot be used in
linear space.

If you set @export_profile to the filename of an ICC profile, the image
will be transformed to the target colourspace before writing to the
output. You can also give an @import_profile which will be used if the
input image has no ICC profile, or if the profile embedded in the
input image is broken.

Use @intent to set the rendering intent for any ICC transform. The default
is #VIPS_INTENT_RELATIVE.

See also: vips_thumbnail_buffer().</doc>
      <source-position filename="include/vips/resample.h" line="75"/>
      <return-value transfer-ownership="none">
        <doc xml:space="preserve"
             filename="resample/thumbnail.c"
             line="1177">0 on success, -1 on error.</doc>
        <type name="gint" c:type="int"/>
      </return-value>
      <parameters>
        <parameter name="filename" transfer-ownership="none">
          <doc xml:space="preserve"
               filename="resample/thumbnail.c"
               line="1116">file to read from</doc>
          <type name="utf8" c:type="const char*"/>
        </parameter>
        <parameter name="out"
                   direction="out"
                   caller-allocates="0"
                   transfer-ownership="full">
          <doc xml:space="preserve"
               filename="resample/thumbnail.c"
               line="1117">output image</doc>
          <type name="Image" c:type="VipsImage**"/>
        </parameter>
        <parameter name="width" transfer-ownership="none">
          <doc xml:space="preserve"
               filename="resample/thumbnail.c"
               line="1118">target width in pixels</doc>
          <type name="gint" c:type="int"/>
        </parameter>
        <parameter name="..." transfer-ownership="none">
          <doc xml:space="preserve"
               filename="resample/thumbnail.c"
               line="1119">%NULL-terminated list of optional named arguments</doc>
          <varargs/>
        </parameter>
      </parameters>
    </function>

The doc node has a pretty strict format, so it should be easy to turn to markdown etc. You just need to load that xml and generate something better than this:

https://github.com/libvips/ruby-vips/blob/master/lib/vips/methods.rb#L2002

[Nakilon]

1. Your gist looks shorter than what you've copypasted here: https://gist.github.com/jcupitt/eef9d24d19d345da6dccbb8e569951c7#file-vips-8-0-gir-L19860-L19876

2. Maybe stupid question but is this rdoc format? https://github.com/libvips/ruby-vips/blob/master/lib/vips/methods.rb#L2002-L2016 -- I was just never doing it. So the goal is to convert that xml format to this format and add the <docs> node? AFAIK you've already done some big work on generating ruby docs so to avoid reinventing that wheel this probably could be done in just an adding a one more step in the end using Nokogiri.

[jcupitt]

It's too big for a gist -- you have to press "download" to see the whole thing. If you build libvips from source the file is generated for you locally, of course.

It's using yard. The current generator is here:
`
https://github.com/libvips/ruby-vips/blob/master/lib/vips/image.rb#L1434

Of course that's done with introspection rather than from the gir file. You could do some kind of combined approach, of course.

You'd need to reformat the <doc> node a bit:

• find and remove Optional args section (easier to generate that from introspection)
• spot @parameter, name(), #name and '%name` and rewrite for yard
• it uses markdown, so translate that to yard as well as you can