CLIs: reorder options, explain -i vs -di

src/eynollah/cli.py

@@ -12,18 +12,18 @@ def main():
     pass
 
 @main.command()
-@click.option(
-    "--dir_in",
-    "-di",
-    help="directory of PAGE-XML input files",
-    type=click.Path(exists=True, file_okay=False),
-)
 @click.option(
     "--input",
     "-i",
     help="PAGE-XML input filename",
     type=click.Path(exists=True, dir_okay=False),
 )
+@click.option(
+    "--dir_in",
+    "-di",
+    help="directory of PAGE-XML input files (instead of --input)",
+    type=click.Path(exists=True, file_okay=False),
+)
 @click.option(
     "--out",
     "-o",
@@ -45,7 +45,8 @@ def main():
     help="Override log level globally to this",
 )
 
-def machine_based_reading_order(dir_in, input, out, model, log_level):
+def machine_based_reading_order(input, dir_in, out, model, log_level):
+    assert bool(input) != bool(dir_in), "Either -i (single input) or -di (directory) must be provided, but not both."
     orderer = machine_based_reading_order_on_layout(model, dir_out=out)
     if log_level:
         orderer.logger.setLevel(getLevelName(log_level))
@@ -68,7 +69,7 @@ def machine_based_reading_order(dir_in, input, out, model, log_level):
 @click.option(
     "--dir_in",
     "-di",
-    help="directory of input images",
+    help="directory of input images (instead of --image)",
     type=click.Path(exists=True, file_okay=False),
 )
 @click.option(
@@ -85,7 +86,7 @@ def machine_based_reading_order(dir_in, input, out, model, log_level):
     help="Override log level globally to this",
 )
 def binarization(patches, model_dir, input_image, dir_in, output, log_level):
-    assert (dir_in is None) != (input_image is None), "Specify either -di and or -i not both"
+    assert bool(input_image) != bool(dir_in), "Either -i (single input) or -di (directory) must be provided, but not both."
     binarizer = SbbBinarizer(model_dir)
     if log_level:
         binarizer.log.setLevel(getLevelName(log_level))
@@ -116,7 +117,7 @@ def binarization(patches, model_dir, input_image, dir_in, output, log_level):
 @click.option(
     "--dir_in",
     "-di",
-    help="directory of input images",
+    help="directory of input images (instead of --image)",
     type=click.Path(exists=True, file_okay=False),
 )
 @click.option(
@@ -151,8 +152,8 @@ def binarization(patches, model_dir, input_image, dir_in, output, log_level):
 )
 
 def enhancement(image, out, overwrite, dir_in, model, num_col_upper, num_col_lower, save_org_scale,  log_level):
+    assert bool(image) != bool(dir_in), "Either -i (single input) or -di (directory) must be provided, but not both."
     initLogging()
-    assert image or dir_in, "Either a single image -i or a dir_in -di is required"
     enhancer = Enhancer(
         model,
         dir_out=out,
@@ -191,7 +192,7 @@ def enhancement(image, out, overwrite, dir_in, model, num_col_upper, num_col_low
 @click.option(
     "--dir_in",
     "-di",
-    help="directory of input images",
+    help="directory of input images (instead of --image)",
     type=click.Path(exists=True, file_okay=False),
 )
 @click.option(
@@ -400,7 +401,7 @@ def layout(image, out, overwrite, dir_in, model, save_images, save_layout, save_
     assert not extract_only_images or not tables, "Image extraction -eoi can not be set alongside tables -tab"
     assert not extract_only_images or not right2left, "Image extraction -eoi can not be set alongside right2left -r2l"
     assert not extract_only_images or not headers_off, "Image extraction -eoi can not be set alongside headers_off -ho"
-    assert image or dir_in, "Either a single image -i or a dir_in -di is required"
+    assert bool(image) != bool(dir_in), "Either -i (single input) or -di (directory) must be provided, but not both."
     eynollah = Eynollah(
         model,
         dir_out=out,
@@ -447,44 +448,44 @@ def layout(image, out, overwrite, dir_in, model, save_images, save_layout, save_
     help="input image filename",
     type=click.Path(exists=True, dir_okay=False),
 )
-@click.option(
-    "--overwrite",
-    "-O",
-    help="overwrite (instead of skipping) if output xml exists",
-    is_flag=True,
-)
 @click.option(
     "--dir_in",
     "-di",
-    help="directory of input images",
+    help="directory of input images (instead of --image)",
     type=click.Path(exists=True, file_okay=False),
 )
 @click.option(
     "--dir_in_bin",
     "-dib",
-    help="directory of binarized images. This should be given if you want to do prediction based on both rgb and bin images. And all bin images are png files",
+    help="directory of binarized images (in addition to --dir_in for RGB images; filename stems must match the RGB image files, with '.png' suffix).\nPerform prediction using both RGB and binary images. (This does not necessarily improve results, however it may be beneficial for certain document images.)",
     type=click.Path(exists=True, file_okay=False),
 )
-@click.option(
-    "--out",
-    "-o",
-    help="directory to write output xml data",
-    type=click.Path(exists=True, file_okay=False),
-    required=True,
-)
 @click.option(
     "--dir_xmls",
     "-dx",
-    help="directory of xmls",
+    help="directory of input PAGE-XML files (in addition to --dir_in; filename stems must match the image files, with '.xml' suffix).",
+    type=click.Path(exists=True, file_okay=False),
+    required=True,
+)
+@click.option(
+    "--out",
+    "-o",
+    help="directory for output PAGE-XML files",
     type=click.Path(exists=True, file_okay=False),
     required=True,
 )
 @click.option(
     "--dir_out_image_text",
     "-doit",
-    help="directory of images with predicted text",
+    help="directory for output images, newly rendered with predicted text",
     type=click.Path(exists=True, file_okay=False),
 )
+@click.option(
+    "--overwrite",
+    "-O",
+    help="overwrite (instead of skipping) if output xml exists",
+    is_flag=True,
+)
 @click.option(
     "--model",
     "-m",
@@ -515,12 +516,6 @@ def layout(image, out, overwrite, dir_in, model, save_images, save_layout, save_
     is_flag=True,
     help="if this parameter set to true, cropped textline images will not be masked with textline contour.",
 )
-@click.option(
-    "--prediction_with_both_of_rgb_and_bin",
-    "-brb/-nbrb",
-    is_flag=True,
-    help="If this parameter is set to True, the prediction will be performed using both RGB and binary images. However, this does not necessarily improve results; it may be beneficial for certain document images.",
-)
 @click.option(
     "--batch_size",
     "-bs",
@@ -543,7 +538,7 @@ def layout(image, out, overwrite, dir_in, model, save_images, save_layout, save_
     help="Override log level globally to this",
 )
 
-def ocr(image, overwrite, dir_in, dir_in_bin, out, dir_xmls, dir_out_image_text, model, model_name, tr_ocr, export_textline_images_and_text, do_not_mask_with_textline_contour, prediction_with_both_of_rgb_and_bin, batch_size, dataset_abbrevation, min_conf_value_of_textline_text, log_level):
+def ocr(image, dir_in, dir_in_bin, dir_xmls, out, dir_out_image_text, overwrite, model, model_name, tr_ocr, export_textline_images_and_text, do_not_mask_with_textline_contour, batch_size, dataset_abbrevation, min_conf_value_of_textline_text, log_level):
     initLogging()
         
     assert not model or not model_name, "model directory  -m can not be set alongside specific model name --model_name"
@@ -552,8 +547,7 @@ def ocr(image, overwrite, dir_in, dir_in_bin, out, dir_xmls, dir_out_image_text,
     assert not export_textline_images_and_text or not batch_size, "Exporting textline and text  -etit can not be set alongside batch size -bs"
     assert not export_textline_images_and_text or not dir_in_bin, "Exporting textline and text  -etit can not be set alongside directory of bin images -dib"
     assert not export_textline_images_and_text or not dir_out_image_text, "Exporting textline and text  -etit can not be set alongside directory of images with predicted text -doit"
-    assert not export_textline_images_and_text or not prediction_with_both_of_rgb_and_bin, "Exporting textline and text  -etit can not be set alongside prediction with both rgb and bin -brb"
-    assert (bool(image) ^ bool(dir_in)), "Either -i (single image) or -di (directory) must be provided, but not both."
+    assert bool(image) != bool(dir_in), "Either -i (single image) or -di (directory) must be provided, but not both."
     eynollah_ocr = Eynollah_ocr(
         image_filename=image,
         dir_xmls=dir_xmls,