Update docstrings

Author: mittagessen

kraken/align.py

@@ -18,8 +18,8 @@
 align
 ~~~~~
 
-A character alignment module using a network output lattice and ground truth to
-accuractely determine grapheme locations in input data.
+Legacy API for forced alignment using the network output lattice. New
+applications should use the ForcedAlignmentTaskModel from kraken.tasks.
 """
 import logging
 import warnings

kraken/binarization.py

@@ -17,7 +17,8 @@
 kraken.binarization
 ~~~~~~~~~~~~~~~~~~~
 
-An adaptive binarization algorithm.
+An adaptive binarization algorithm. This code is legacy and only remains for
+historical reasons. Binarization is no longer necessary for most workflows.
 """
 import logging
 import warnings

kraken/blla.py

@@ -16,8 +16,8 @@
 kraken.blla
 ~~~~~~~~~~~
 
-Trainable layout analysis tools for kraken for line and region detection. The
-line recognizer uses the baseline paradigm.
+Legacy API for inference using the trainable baseline and region detection
+segmenter. New code should use the SegmentationTaskModel from kraken.tasks.
 """
 import PIL
 import uuid

kraken/models/_coreml.py

@@ -1,8 +1,8 @@
 """
-kraken.models.loaders
+kraken.models._coreml
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Implementation for model metadata and weight loading from various formats.
+Implementation for weight loading from a CoreML NeuralNetwork object.
 """
 import torch
 

kraken/models/loaders.py

@@ -42,6 +42,17 @@ def load_models(path: Union[str, 'PathLike'], tasks: Optional[Sequence[_T_tasks]
 def load_safetensors(path: Union[str, PathLike], tasks: Optional[Sequence[_T_tasks]] = None) -> list[BaseModel]:
     """
     Loads one or more models in safetensors format and returns them.
+
+    Args:
+        path: Path to the safetensors file.
+        tasks: Filter for model types to load from file.
+
+    Returns:
+        A list of models.
+
+    Raises:
+        ValueError: When model metadata is incomplete or the safetensors file
+        is invalid.
     """
     from torch import nn
     from safetensors import safe_open, SafetensorError
@@ -74,7 +85,18 @@ def load_safetensors(path: Union[str, PathLike], tasks: Optional[Sequence[_T_tas
 
 def load_coreml(path: Union[str, PathLike], tasks: Optional[Sequence[_T_tasks]] = None) -> list[BaseModel]:
     """
-    Loads a model in coreml format.
+    Loads a model in CoreML format.
+
+    Args:
+        path: Path to the coreml file.
+        tasks: Filter for model types to load from file.
+
+    Returns:
+        A list of models.
+
+    Raises:
+        ValueError: When model metadata is incomplete or the coreml file
+        is invalid.
     """
     root_logger = logging.getLogger()
     level = root_logger.getEffectiveLevel()
@@ -83,6 +105,8 @@ def load_coreml(path: Union[str, PathLike], tasks: Optional[Sequence[_T_tasks]]
     root_logger.setLevel(level)
     from google.protobuf.message import DecodeError
 
+    models = []
+
     if isinstance(path, PathLike):
         path = path.as_posix()
     try:
@@ -111,12 +135,14 @@ def load_coreml(path: Union[str, PathLike], tasks: Optional[Sequence[_T_tasks]]
         weights.update(cml_parser(spec))
 
     model.load_state_dict(weights)
+    models.append(model)
 
     # construct additional models if auxiliary layers are defined.
 
-    # if 'aux_layers' in mlmodel.user_defined_metadata:
-    #     logger.info('Deserializing auxiliary layers.')
+    if 'aux_layers' in mlmodel.user_defined_metadata:
+        logger.info('Deserializing auxiliary layers.')
+
+        nn.aux_layers = {k: cls(v).nn.get_submodule(k) for k, v in json.loads(mlmodel.user_defined_metadata['aux_layers']).items()}
 
-    #     nn.aux_layers = {k: cls(v).nn.get_submodule(k) for k, v in json.loads(mlmodel.user_defined_metadata['aux_layers']).items()}
+    return models
 
-    return [model]

kraken/pageseg.py

@@ -17,7 +17,8 @@
 kraken.pageseg
 ~~~~~~~~~~~~~~
 
-Layout analysis methods.
+The legacy bounding box segmentation method using conventional image processing
+techniques.
 """
 import logging
 import uuid

kraken/rpred.py

@@ -16,7 +16,8 @@
 kraken.rpred
 ~~~~~~~~~~~~
 
-Generators for recognition on lines images.
+Legacy line text recognition API. New code should use the RecognitionTaskModel
+from kraken.tasks which is more versatile and offers higher performance.
 """
 import logging
 import warnings

kraken/serialization.py

@@ -12,6 +12,13 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 # or implied. See the License for the specific language governing
 # permissions and limitations under the License.
+"""
+kraken.serialization
+~~~~~~~~~~~~~~~~~~~~
+
+A serializer using Jinja2 templates to write segmentation and recognition
+results.
+"""
 import datetime
 import importlib.metadata
 import logging

kraken/tasks/segmentation.py

@@ -2,7 +2,7 @@
 kraken.lib.tasks.segmentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Wrappers around models for specific tasks.
+A wrapper around models for layout analysis and reading order determination.
 """
 import torch
 import shapely.geometry as geom
@@ -28,7 +28,7 @@
 logger = logging.getLogger(__name__)
 
 
-class SegmentationTaskModel:
+class SegmentationTaskModel(nn.Module):
     """
     A wrapper class collecting one or more models that perform segmentation.