improve docstrings, fix indentation
@@ -252,25 +252,18 @@ class Workspace():
Given a PageType object, ``page``, extract its PIL.Image from
AlternativeImage if it exists. Otherwise extract the PIL.Image
- from imageFilename, and crop it if a Border exists, and rotate
- it if an orientation angle exists. Otherwise just return it.
-
- When an AlternativeImage exists, if ``feature_selector`` and/or
- ``feature_filter`` is given, select/filter among the available
- AlternativeImages the last which contains all of the selected
- but none of the filtered features (i.e. @comments classes), or
- raise an error. Otherwise use the last one.
- Regardless, if the chosen AlternativeImage does not have "cropped",
- but a Border exists, then crop it. And if the chosen AlternativeImage
- does not have "deskewed" and an orientation exists, then rotate it.
-
- When no AlternativeImage exists, if ``feature_selector`` and/or
- ``feature_filter`` is given, verify that the image to be produced from
- imageFilename contains all of the selected but none of the filtered
- features, or raise an error.
- Regardless, crop to the segment polygon, and respect any orientation
- angle annotated for the page (from page-level deskewing) by rotating
- the image.
+ from imageFilename. Also crop it if a Border exists, and rotate
+ it if an @orientation exists. Otherwise just return it.
+
+ If ``feature_selector`` and/or ``feature_filter`` is given, then
+ select/filter among imageFilename and all AlternativeImages the
+ last which contains all of the selected but none of the filtered
+ features (i.e. @comments classes), or raise an error.
+
+ If the chosen image does not have "cropped", but a Border exists,
+ then crop it (unless "cropped" is also being filtered). And if the
+ chosen image does not have "deskewed", but an @orientation exists,
+ then rotate it (unless "deskewed" is also being filtered).
Cropping uses a polygon mask (not just the rectangle).
@@ -390,25 +383,22 @@ class Workspace():
def image_from_segment(self, segment, parent_image, parent_xywh, feature_selector='', feature_filter=''):
"""Extract a segment image from its parent's image.
- Given a PIL.Image of the parent, ``parent_image``, and its
+ Given a PIL.Image of the parent, ``parent_image``, with its
absolute coordinates, ``parent_xywh``, and a PAGE segment
(TextRegionType / TextLineType / WordType / GlyphType) object
which is logically contained in it, ``segment``, extract its
- PIL.Image from AlternativeImage (if it exists), or via cropping
- from ``parent_image``.
-
- When an AlternativeImage exists, if ``feature_selector`` and/or
- ``feature_filter`` is given, select/filter among the available
- AlternativeImages the last which contains all of the selected
- but none of the filtered features (i.e. @comments classes), or
- raise an error. Otherwise use the last one.
- Regardless, if the chosen AlternativeImage does not have "deskewed",
- and an orientation exists, then rotate it.
-
- When no AlternativeImage exists, if ``feature_selector`` and/or
- ``feature_filter`` is given, verify that the image to be produced from
- parent image contains all of the selected but none of the filtered
- features, or raise an error.
+ PIL.Image from AlternativeImage if it exists. Otherwise produce
+ an image via cropping from ``parent_image``.
+
+ If ``feature_selector`` and/or ``feature_filter`` is given, then
+ select/filter among the cropped ``parent_image`` and the available
+ AlternativeImages the last which contains all of the selected but none
+ of the filtered features (i.e. @comments classes), or raise an error.
+
+ If the chosen AlternativeImage does not have "deskewed", but
+ an @orientation exists, then rotate it (unless "deskewed" is
+ also being filtered).
+
Regardless, respect any orientation angle annotated for the parent
(from parent-level deskewing) by rotating the image, and compensating
the segment coordinates in an inverse transformation (i.e. translation
