docs: Provide snippet to get a tile's image

NEWS.md

@@ -8,6 +8,7 @@
 * Layer names are now trimmed when edited in the UI, to avoid accidental whitespace
 * Scripting: Added API for working with worlds (#3539)
 * Scripting: Added Tile.image for accessing a tile's image data
+* Scripting: Added Image.copy overload that takes a rectangle
 * Scripting: Added Tileset.imageFileName and ImageLayer.imageFileName
 * Scripting: Added FilePath.localFile and FileEdit.fileName (string alternatives to Qt.QUrl properties)
 * Scripting: Made Tileset.margin and Tileset.tileSpacing writable

docs/scripting-doc/index.d.ts

@@ -2203,6 +2203,15 @@ declare class Image {
    */
   setColorTable(colors: number[] | string[]): void;
 
+  /**
+   * Copies the given rectangle to a new image object.
+   *
+   * When no rectangle is given, the entire image is copied.
+   *
+   * @since 1.11
+   */
+  copy(rect?: rect) : Image;
+
   /**
    * Copies the given rectangle to a new image object.
    */
@@ -2466,6 +2475,16 @@ declare class Tile extends TiledObject {
    * Returns the image of this tile, or the image of its tileset if it doesn't
    * have an individual one.
    *
+   * Note that a tile represents a sub-rectangle of its image (or its tileset's
+   * image), even if is part of an image collection tileset. The {@link
+   * imageRect} property provides access to this sub-rectangle. If you need a
+   * copy of the tile's image that is already cropped to this sub-rectangle,
+   * you can use the following snippet:
+   *
+   * ```js
+   * let image = tile.image.copy(tile.imageRect);
+   * ```
+   *
    * You can assign an {@link Image} to this property to change the tile's
    * image. See {@link setImage} for more information.
    *

src/tiled/scriptimage.cpp

@@ -108,6 +108,11 @@ void ScriptImage::setColorTable(QJSValue colors)
     mImage.setColorTable(std::move(colorTable));
 }
 
+ScriptImage *ScriptImage::copy(QRect rect) const
+{
+    return new ScriptImage(mImage.copy(rect));
+}
+
 ScriptImage *ScriptImage::copy(int x, int y, int w, int h) const
 {
     return new ScriptImage(mImage.copy(x, y, w, h));

src/tiled/scriptimage.h

@@ -146,6 +146,7 @@ class ScriptImage : public QObject
 
     Q_INVOKABLE void setColorTable(QJSValue colors);
 
+    Q_INVOKABLE Tiled::ScriptImage *copy(QRect rect = {}) const;
     Q_INVOKABLE Tiled::ScriptImage *copy(int x, int y, int w, int h) const;
     Q_INVOKABLE Tiled::ScriptImage *scaled(int w, int h,
                                            AspectRatioMode aspectMode = IgnoreAspectRatio,