micat 0.1.0__py3-none-any.whl

micat/__init__.py

@@ -0,0 +1,13 @@
+"""Micat is for Microscopy Calibration and Testing using USAF resolution targets.
+
+Micat is planned to become a larger library of calibration tools, but for now the only
+calibration it does is calibrate the size of pixels in a micrograph. The internal API
+for these features are in `usafcal`.
+
+
+
+"""
+
+from . import usafcal
+
+__all__ = ["usafcal"]

micat/__main__.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python
+"""The module used for CLI operation."""
+
+import argparse
+import os
+from datetime import datetime
+
+import openflexure_metadata
+import piexif
+
+import micat
+from micat.usafcal_report import export_results
+
+METADATA_UNREAD_VALUE = "unknown"
+
+
+def _create_cli_parsers() -> tuple[argparse.ArgumentParser, argparse.ArgumentParser]:
+    """Create the command line argument parser.
+
+    :return: The main parser and the subparser for the usafcal command.
+    """
+    parser = argparse.ArgumentParser(
+        description="Micat Microscopy Calibration and Testing",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(
+        help="Available commands listed below", metavar="<command>", dest="command"
+    )
+    parser_usafcal = subparsers.add_parser(
+        "usafcal", help="Analyse an image of a USAF target"
+    )
+    parser_usafcal.add_argument(
+        "imagefiles", type=str, nargs="+", help="the image file to analyse"
+    )
+    parser_usafcal.add_argument("--verbose", "-v", action="count")
+    parser_usafcal.add_argument("--outdir", "-O", help="Directory for saved data")
+    parser_usafcal.add_argument(
+        "--group",
+        "-g",
+        type=int,
+        default=7,
+        help="Set smallest group found, see PDF output! (default: 7)",
+    )
+    parser_usafcal.add_argument(
+        "--element",
+        "-e",
+        type=int,
+        default=6,
+        help="Set smallest element found, see PDF output! (default: 6)",
+    )
+    parser_usafcal.add_argument(
+        "--largest",
+        "-L",
+        action="count",
+        help="Makes --group and --element to refer to largest not smallest",
+    )
+    parser_help = subparsers.add_parser(
+        "help", help="Run 'help <command>' for detailed help"
+    )
+    parser_help.add_argument(
+        "h_command",
+        metavar="<command>",
+        nargs="?",
+        type=str,
+        help="Command to show help for",
+    )
+
+    return parser, parser_usafcal
+
+
+def main() -> None:
+    """Run Micat.
+
+    This is the main function when Micat is run as a CLI tool.
+    """
+    parser, parser_usafcal = _create_cli_parsers()
+    args = parser.parse_args()
+
+    if args.command == "usafcal":
+        _run_usafcal(args)
+
+    elif args.command == "help":
+        if args.h_command is None:
+            parser.print_help()
+        elif args.h_command == "usafcal":
+            print(
+                "\n"
+                "Analyse images of USAF 1951 Resolution Targets to calibrate the "
+                "field of view and the numper of microns per pixel.\n"
+            )
+            print(parser_usafcal.format_help())
+        else:
+            print(f"Invalid  micat command {args.h_command}\n\n")
+            parser.print_help()
+    else:
+        print(f"Invalid micat command {args.command}")
+        return
+
+
+def _run_usafcal(args: argparse.Namespace) -> None:
+    """Run the USAF Target calibration based on the specified command line arguments."""
+    if not (1 <= args.group <= 7 and 1 <= args.element <= 6):
+        raise ValueError(
+            "Group must be between 1 and 7. Element must be between 1 and 6."
+        )
+
+    verbose = args.verbose is not None
+
+    largest = args.largest is not None
+
+    for filepath in args.imagefiles:
+        if verbose:
+            print("Analysing %s" % filepath)
+
+        directory, filename = os.path.split(filepath)
+        basefile, ext = os.path.splitext(filename)
+
+        target = micat.usafcal.analyse_file(
+            filepath,
+            group=args.group,
+            element=args.element,
+            smallest=not largest,
+        )
+
+        if args.outdir is not None:
+            directory = args.outdir
+
+        os.makedirs(directory, exist_ok=True)
+
+        if verbose:
+            print("Exporting results...")
+        metadata = read_metadata(filepath)
+        export_results(
+            target, os.path.join(directory, basefile + "_USAF_calibration"), metadata
+        )
+        if verbose:
+            print("Done!")
+
+
+def read_metadata(filepath: str) -> dict:
+    """Read selected image metadata from the given filepath."""
+    exif = piexif.load(filepath)
+
+    user_comments = openflexure_metadata.get_exif_usercomment_json(exif)
+    capture_time = openflexure_metadata.get_capture_time(exif)
+
+    # Fully structured default schema
+    metadata: dict = {
+        "camera": METADATA_UNREAD_VALUE,
+        "system": {
+            "hostname": METADATA_UNREAD_VALUE,
+            "microscope-uuid": METADATA_UNREAD_VALUE,
+            "version": METADATA_UNREAD_VALUE,
+            "version_source": METADATA_UNREAD_VALUE,
+        },
+        "capture_time": METADATA_UNREAD_VALUE,
+        "capture_time_unix": METADATA_UNREAD_VALUE,
+    }
+
+    if isinstance(user_comments, dict):
+        metadata["camera"] = user_comments.get("camera", METADATA_UNREAD_VALUE)
+
+        system = user_comments.get("system")
+        if isinstance(system, dict):
+            metadata["system"]["hostname"] = system.get(
+                "hostname", METADATA_UNREAD_VALUE
+            )
+            metadata["system"]["microscope-uuid"] = system.get(
+                "microscope-uuid", METADATA_UNREAD_VALUE
+            )
+            metadata["system"]["version"] = system.get("version", METADATA_UNREAD_VALUE)
+            metadata["system"]["version_source"] = system.get(
+                "version_source", METADATA_UNREAD_VALUE
+            )
+
+    # Capture time
+    if capture_time is not None:
+        metadata["capture_time"] = datetime.fromtimestamp(capture_time).strftime(
+            "%d %B %Y, %H:%M"
+        )
+        metadata["capture_time_unix"] = capture_time
+    return metadata
+
+
+if __name__ == "__main__":
+    main()

micat/report_assets/emblem_pink.svg

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 263 163" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g id="path3773" transform="matrix(0.376342,0,0,0.376342,-8.65757,-85.6939)">
+        <path d="M212.85,344.652C234.052,276.913 297.347,227.702 372.047,227.702C446.747,227.702 510.042,276.913 531.245,344.652L531.246,344.656C531.789,346.391 532.304,348.138 532.791,349.896C556.452,421.618 655.593,393.868 655.593,393.868L721.09,563.056L472.356,659.347L430.306,550.728L430.129,550.794L406.853,490.142C408.621,489.464 410.361,488.736 412.072,487.962C419.736,484.232 426.404,480.109 432.198,475.703C447.995,463.209 459.586,446.041 465.257,426.69C473.38,395.32 463.384,366.691 463.101,365.891C449.309,328.959 413.54,302.366 372.047,302.366C330.554,302.366 294.785,328.959 280.994,365.891C280.711,366.689 270.714,395.319 278.838,426.69C284.509,446.041 296.099,463.209 311.897,475.703C317.69,480.109 324.359,484.232 332.023,487.962C333.734,488.736 335.474,489.464 337.242,490.142L337.166,490.34L313.965,550.794L313.788,550.728L271.739,659.347L23.004,563.056L88.501,393.868C88.501,393.868 187.642,421.618 211.303,349.896C211.79,348.138 212.306,346.391 212.849,344.656L212.85,344.652Z" style="fill:rgb(197,36,127);fill-rule:nonzero;"/>
+    </g>
+</svg>

micat/report_assets/main.typ

@@ -0,0 +1,154 @@
+#let report-title = "Micat Calibration Report"
+#let um = $upright(#sym.mu m)$
+#let um2 = $upright(#sym.mu m^2)$
+#let report-date = datetime.today().display("[day] [month repr:long] [year]")
+
+#let calibration_data = json(bytes(sys.inputs.calibration_data))
+
+#set document(
+  title: report-title,
+)
+
+#set page(
+  paper: "a4",
+  margin: (x: 2.5cm, y: 2cm),
+  numbering: "1",
+)
+
+#set text(
+  font: "Open Sans",
+  size: 12pt,
+)
+
+#set heading(numbering: "1.")
+#show heading: set block(below: 2em)
+
+#set page(
+  paper: "a4",
+  margin: (x: 2.5cm, y: 2cm),
+  footer: context [
+    #align(center)[
+      #text(size: 9pt, fill: gray)[
+        Micat Calibration Report · Micat Version #calibration_data.software_version
+      ]
+      #linebreak()
+      #text(size: 9pt, fill: gray)[
+        Page #counter(page).display("1")
+        of #counter(page).final().at(0)
+        · #report-date
+      ]
+    ]
+  ]
+)
+#grid(
+  columns: (auto, auto),
+  gutter: 20pt,
+  align: horizon+center,
+  image("emblem_pink.svg", height: 40pt),
+  text(size: 22pt, weight: 700)[#report-title]
+)
+
+Microscope name: *#calibration_data.metadata.system.hostname*
+
+= USAF Resolution Target Analysis Output
+
+Effective size of pixel = #calibration_data.um_per_px #sym.plus.minus  #calibration_data.um_per_px_uncert #um
+
+Field of view = (#calibration_data.fov0 #sym.plus.minus  #calibration_data.fov0_uncert #sym.times #calibration_data.fov1 #sym.plus.minus  #calibration_data.fov1_uncert) #um2
+
+These uncertainties are from the regression only and may be an under estimation.
+
+This is based on an image size of #calibration_data.fov_px.at(0) #sym.times #calibration_data.fov_px.at(1) pixels, and will need scaling for other images.
+
+Greyscale input image has hashlib md5 hash #calibration_data.md5_hash
+
+Report produced on #report-date
+
+Micat analysis software version: #calibration_data.software_version  
+
+#text(blue)[NOTE: These results are only valid if all elements in the following image are correctly labelled.]
+
+#pagebreak()
+
+= USAF Resolution Labelled Image
+
+#text(blue)[Ensure that the elements have the correct group and element number before using these results.]
+
+Smallest labelled element is group #calibration_data.smallest_group, element #calibration_data.smallest_element.
+
+#figure(
+  caption: [Labelled USAF resolution target used for calibration. Red boxes mark a set of 3 lines, each of which will be surrounded by a dark blue box. Light blue highlights the squares, and green highlights other features including numbers.],
+  [
+    #align(center)[
+      #image("file.jpg", width: 80%, fit:"contain")
+    ]
+  ]
+)
+
+#pagebreak()
+
+= USAF Resolution Plots
+
+
+The spacing plot should be an increasing, linear fit. The residuals should be distributed around y = 0 with no overall trends.
+
+#image("regression.png", width:100%)
+
+= System Information
+
+// Produce the rows from given labels and variables, handling either dicts or strings
+#let render-metadata(label, value) = {
+  if type(value) == dictionary {
+    let rows = value.pairs().map(((k, v)) => (k, str(v)))
+    (table.cell(colspan: 2)[*#label*],) + rows.flatten()
+  } else {
+    (table.cell(colspan: 2)[*#label*], table.cell(colspan: 2)[#str(value)])
+  }
+}
+
+#table(
+  columns: (auto, 1fr),
+  stroke: 0.5pt,
+  fill: (_, row) => if calc.odd(row) { luma(245) } else { white },
+  table.header(table.cell(colspan: 2, align: center)[*Metadata*]),
+  ..render-metadata("Camera", calibration_data.metadata.camera),
+  ..render-metadata("Microscope", calibration_data.metadata.system),
+  table.cell(colspan: 2)[*Capture Time*],
+  [capture_time], [#calibration_data.metadata.capture_time],
+  [capture_time_unix], [#str(calibration_data.metadata.capture_time_unix)],
+)
+
+#pagebreak()
+
+
+= Methodology
+
+Calibration was performed using an automated analysis of a USAF 1951 resolution target image.
+
+The input image is first converted to greyscale and thresholded to identify contours. 
+Detected features are classified based on shape: rectangular features with an aspect 
+ratio consistent with USAF bars (approximately 5:1) are retained, while other features 
+are discarded or labelled separately.
+
+Bars are grouped into sets of three based on their relative spacing and alignment, 
+forming individual USAF elements. The spacing between bars is measured in pixels, and 
+each element is assigned a group and element number based on the known geometric 
+progression of the USAF target.
+
+The physical spacing corresponding to each element is calculated using the standard 
+relationship for line pairs per millimetre:
+
+$ 2^{(g + (e - 1)/6)} $
+
+where $g$ is the group number and $e$ is the element number.
+
+A linear fit is performed between the measured pixel spacing and the known physical 
+spacing. The gradient of this fit is used to determine the calibration factor 
+(micrometres per pixel), and the associated uncertainty is estimated from the 
+covariance of the fit.
+
+The field of view is then calculated from the image dimensions and the calibrated 
+pixel size.
+
+Further implementation details and source code are available at:
+#link("https://gitlab.com/openflexure/micat")[https://gitlab.com/openflexure/micat]