Add 'merge-convert jpeg' command

Author: Argmaster

docs/90_development/50_testing.md

@@ -0,0 +1,25 @@
+# Testing
+
+PyGerber uses pytest for testing purposes. All tests are contained in `tests/`
+directory. Tests are grouped in 3 categories:
+
+- `unit`: tests for individual functionalities, testing those in separation from rest of
+  the project
+- `e2e`: end-to-end tests, testing full flows from user provided data to user consumable
+  output
+- `examples`: automatically validated code exampled used in documentation
+
+Assets used as input data for tests are stored in `tests/assets/` directory. Assets used
+as output reference data are stored in separate repository:
+[pygerber_reference_assets](https://github.com/PyGerber/pygerber_reference_assets).
+
+Example of test making use of reference data can be found in
+`test/unit/test_console/test_gerber.py` - `test_gerber_convert_png`. Reference asset
+must be generated by special execution mode of the test, guarded by
+`is_regeneration_enabled` fixture. To regenerate test asset (or generate it for the
+first time) you have to run that test **alone** with `--regenerate` flag. To commit
+regenerated assets, use `--auto-commit-regenerated` flag.
+
+```bash
+pytest -k test_gerber_convert_png --regenerate --auto-commit-regenerated
+```

src/pygerber/console/gerber.py

@@ -540,6 +540,40 @@ def merge_convert_png(
         raise NotImplementedError(msg)
 
 
+@merge_convert.command("jpeg")
+@click.argument("sources", nargs=-1)
+@_get_output_file_option()
+@_get_dpmm_option()
+@_get_file_type_option()
+@_get_raster_implementation_option("pillow")
+def merge_convert_jpeg(
+    sources: str,
+    output: str,
+    file_type: str,
+    dpmm: int,
+    implementation: str,
+) -> None:
+    """Convert multiple Gerber images to JPEG image and merge them into one image.
+
+    Images are merged from first to last, thus fist layer is bottom most, last layer
+    is topmost, unobstructed.
+
+    SOURCES - paths to files which are supposed to be rendered and merged.
+    """
+    view = CompositeView(
+        GerberFile.from_file(source, file_type=FileTypeEnum(file_type.upper()))
+        for source in sources
+    )
+
+    if implementation.lower() == "pillow":
+        result = view.render_with_pillow(dpmm)
+        result.save_jpeg(output)
+
+    else:
+        msg = f"Implementation {implementation!r} is not supported."
+        raise NotImplementedError(msg)
+
+
 @gerber.command("lint")
 @click.argument("files", nargs=-1)
 @click.option(

test/assets/reference/pygerber/console/gerber.py

@@ -48,3 +48,8 @@
     REFERENCE_REPOSITORY.file("reference/pygerber/console/merge_convert_png.png"),
     ImageFormat.PNG,
 )
+
+MERGE_CONVERT_JPEG_REFERENCE_IMAGE = ImageAsset[GitFile].new(
+    REFERENCE_REPOSITORY.file("reference/pygerber/console/merge_convert_jpeg.jpeg"),
+    ImageFormat.JPEG,
+)

test/unit/test_console/test_gerber.py

@@ -10,6 +10,7 @@
     bmp,
     format_cmd,
     jpeg,
+    merge_convert_jpeg,
     merge_convert_png,
     png,
     tiff,
@@ -27,6 +28,7 @@
     CONVERT_WEBP_LOSSLESS_REFERENCE_IMAGE,
     CONVERT_WEBP_LOSSY_REFERENCE_IMAGE,
     FORMAT_CMD_REFERENCE_CONTENT,
+    MERGE_CONVERT_JPEG_REFERENCE_IMAGE,
     MERGE_CONVERT_PNG_REFERENCE_IMAGE,
 )
 from test.conftest import cd_to_tempdir
@@ -359,3 +361,40 @@ def test_gerber_merge_convert_png(*, is_regeneration_enabled: bool) -> None:
                 .assert_channel_count(4)
                 .assert_greater_or_equal_values(0.99)
             )
+
+
+MIN_MERGE_JPEG_SSIM = 0.99
+
+
+@tag(Tag.PILLOW, Tag.OPENCV, Tag.SKIMAGE)
+def test_gerber_merge_convert_jpeg(*, is_regeneration_enabled: bool) -> None:
+    runner = CliRunner()
+    with cd_to_tempdir() as temp_path:
+        result = runner.invoke(
+            merge_convert_jpeg,
+            [
+                get_example_path(ExamplesEnum.carte_test_B_Cu).as_posix(),
+                get_example_path(ExamplesEnum.carte_test_B_Mask).as_posix(),
+                get_example_path(ExamplesEnum.carte_test_B_Silkscreen).as_posix(),
+                "-o",
+                "output.jpeg",
+                "-d",
+                "20",
+            ],
+        )
+        logging.debug(result.output)
+        assert result.exit_code == 0
+        assert (temp_path / "output.jpeg").exists()
+
+        image = Image.open(temp_path / "output.jpeg")
+        if is_regeneration_enabled:
+            MERGE_CONVERT_JPEG_REFERENCE_IMAGE.update(image)  # pragma: no cover
+        else:
+            ia = ImageAnalyzer(MERGE_CONVERT_JPEG_REFERENCE_IMAGE.load())
+            assert ia.structural_similarity(image) > MIN_MERGE_JPEG_SSIM
+            ia.assert_same_size(image)
+            (
+                ia.histogram_compare_color(image)
+                .assert_channel_count(4)
+                .assert_greater_or_equal_values(0.99)
+            )