.. This is part of the Photini documentation.
   Copyright (C)  2023-26  Jim Easterbrook.
   See the file ../DOC_LICENSE.txt for copying condidions.

Image regions
=============

The ``Image regions`` tab (keyboard shortcut ``Alt+R``) allows you to select part of a picture and label it with metadata.
This can be useful to identify people in a photograph, or to mark which part of the photograph should remain visible if the image is cropped.
The `IPTC User Guide`_ discusses possible uses of image regions in more detail.

Photini stores image regions in IPTC_, MWG_ (Metadata Working Group), and MP_ (Microsoft Photo 1.2 Schema) formats.
(All are stored in the XMP metadata.)
The MWG format is older and less capable than the IPTC format, for example it cannot store polygonal regions, but it may be compatible with more software.
The MP format can only store rectangular regions that identify a person.

.. image:: ../images/screenshot_270.png

The user interface is disabled until one image file is selected.

.. image:: ../images/screenshot_271.png

The image is shown on the right hand side in a scrollable area.
On the left are one or more tabs showing metadata for each image region.
An empty "placeholder" tab with a faint label number is always included.

.. note::
    You should avoid using "raw" image format photographs as these are often slightly larger than the intended display size.
    This could lead to errors in the size and position of image regions.
    Photini attempts to use the correct area of raw photographs, but this cannot be guaranteed to work in all cases.

.. image:: ../images/screenshot_272.png

.. |plus| unicode:: U+002b

To create a new region, right-click anywhere in the image and choose a region type from the context menu.

.. image:: ../images/screenshot_273.png

The new region (a rectangle in this example) is initially centred on your mouse pointer.

.. image:: ../images/screenshot_274.png

The small squares at each corner of the rectangle can be dragged to change the size and shape.
The entire region can be dragged by clicking within it.

.. image:: ../images/screenshot_275.png

Positioning the region is made easier if you zoom in by holding down the ``Ctrl`` key while scrolling with the mouse scroll wheel.
(The zoom can also be adjusted with ``Ctrl-Plus`` and ``Ctrl-Minus`` key combinations.)

After creating a region you can add metadata about the it.
The ``Region name`` and ``Identifier`` fields are unique labels for the region, but I haven't found a use for them.

The ``Boundary unit`` specifies whether the vertex positions are stored as absolute pixel values or relative proportions of the image width and height.
Don't use pixel values unless you have some other software that requires them.

.. image:: ../images/screenshot_276.png

The most important metadata for a region is probably its "role_".
This is chosen from a "controlled vocabulary" defined by the IPTC.
Photini shows the IPTC names and definitions (as "tooltips") in a drop down menu when you click on the ``Role`` entry.
You can select one or more roles from the list.

.. image:: ../images/screenshot_277.png

The `content type`_ is another controlled vocabulary that allows you to say what's special about the selected area.
The upper part shows the IPTC controlled vocabulary.
The most useful of these is probably ``human``.
The lower part shows MWG "types".
These are primarily intended for use by automatic systems such as face detectors and camera autofocus.

.. image:: ../images/screenshot_278.png

The IPTC and MWG specifications allow any other metadata to be attached to a region.
Photini includes ``Person shown`` and ``Description``, which I think are most likely to be useful.
Names in the ``Person shown`` box are also added to the :doc:`descriptive_metadata` tab's ``Person(s) shown`` box.

Rectangular subject area regions with a description or person's name attached are used by the :doc:`flickr` and :doc:`ipernity` to create "notes".
Please let me know if there is any other metadata you would like to be added.

.. image:: ../images/screenshot_279.png

It can be useful to set cropping regions for an image.
Many social media web sites crop images, typically to square or 16:9 aspect ratio landscape.
This often causes problems such as decapitated bodies.

Note that the first region is now shown with a blue & yellow dashed outline as it is no longer selected.
You can select an unselected region by clicking on it in the image or by clicking on its tab.

.. image:: ../images/screenshot_280.png

The polygon region is initially a triangle shape.
Right-clicking on one of its vertices allows a vertex to be added or deleted.
Note that polygon regions are not saved in MWG metadata.

.. image:: ../images/screenshot_281.png

A vertex can also be added by right-clicking anywhere within the polygon.

.. image:: ../images/screenshot_282.png

Vertices can be added to make shapes of any complexity.

Copy and paste
--------------

.. image:: ../images/screenshot_283.png

An individual region can be copied or deleted by right-clicking within its tab.
Pasting a region overwrites the current region, so you should usually select the empty "placeholder" region before pasting.

.. image:: ../images/screenshot_284.png

Right-clicking outside a region tab allows copying or deleting all the image's regions.
Pasting a set of regions adds them to the existing regions, unless they are already present.


.. _content type:
    https://cv.iptc.org/newscodes/imageregiontype/
.. _IPTC:
    http://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata#image-region
.. _IPTC User Guide:
    https://www.iptc.org/std/photometadata/documentation/userguide/#_image_regions
.. _MP:
    https://learn.microsoft.com/en-us/windows/win32/wic/-wic-people-tagging#microsoft-photo-12-schema
.. _MWG:
    https://en.wikipedia.org/wiki/Metadata_Working_Group
.. _role:
    https://cv.iptc.org/newscodes/imageregionrole/