From 5edf019138e3c891e18aae5bc9cf4bc247063ae8 Mon Sep 17 00:00:00 2001 From: Bradley Lowekamp Date: Thu, 25 Apr 2024 10:46:22 -0400 Subject: [PATCH 1/2] Add workflow documentation for generic 2D EM workflow --- docs/source/workflows/2d_EM.rst | 71 +++++++++++++++++++++++++++++++++ docs/source/workflows/index.rst | 2 + 2 files changed, 73 insertions(+) create mode 100644 docs/source/workflows/2d_EM.rst diff --git a/docs/source/workflows/2d_EM.rst b/docs/source/workflows/2d_EM.rst new file mode 100644 index 00000000..0fb594b1 --- /dev/null +++ b/docs/source/workflows/2d_EM.rst @@ -0,0 +1,71 @@ +**** +2D Electron Microscopy Workflow ( formally known as DM conversion workflow) +**** + +Overview: + +This workflow originally was designed to handle DM3 files form TEM or STEM microscopes but has been extended to handle +other 2D EM image file formats. + +Outputs: + 1. A thumbnail image for each the input images + 2. A key image for each the input images. + +The tools box of `IMOD`_ is used primarily to process the EM images. + +Format Conversion ++++++++++++++++++ + +The first step is to convert the input to a format compatible with the IMOD tool suit (e.g. mrc or tiff). + +Inputs: DM3 or DM4 files +Outputs: MRC files +Steps: + 1. Use the `dm2mrc`_ tool to convert the input files to MRC format. + +Resampling +++++++++++ + +The EM images can be broadly characterized has have a low signal to noise ratio and a high dynamic range with potential +outliers. The resampling or resizing of these images requires advanced algorithms and options that are not available +with conventional image processing tools. Through proper resampling and filtering the images signal to noise ratio can +be improved and the dynamic range can be reduced for better visualization. + +The IMOD tool `newstack`_ is used to resample the images. + +Inputs: MRC or TIFF files +Outputs: TIFF files as 8-bit image +Steps: + 1. Determine the size or dimensions of the input images. + 2. Compute the factor to reduce the size of the input image to the desired key image size. + 3. Use the `newstack`_ tool to filter and resize/shrink the input image to approximately the desired size. + +.. code-block:: bash + newstack -format TIFF -shrink $shrink_factor -antialias 6 -mode 0 -meansd "140,50" input.tiff output.tiff + +The above command should convert any supported scalar pixel input type to an 8-bit image which a dynamic range +reasonable for visualization. The `meansd` values could be considered tunable parameters. + +Output Generation ++++++++++++++++++ + +The final step is to generate the thumbnail and key images with GraphicsMagick. The compression and filtering options +are used for web display. + +Inputs: TIFF files +Outputs: JPEG files +Steps: + 1. Use GraphicsMagick to generate the thumbnail and key images. + +.. code-block:: bash + gm convert -size $output_size -resize $output_size -sharpen 2 -quality 80 input.tiff thumbnail.jpg + +Note: The "resize" option specified the maximum size of a dimension of the output, the other dimension man be smaller to +preserve the input aspect ration. + +The sharpen and quality value are tunable parameters which may vary between thumbnails and key images or may need to be +further turned based on the input image. + +.. _IMOD: https://bio3d.colorado.edu/imod/ +.. _dm2mrc: https://bio3d.colorado.edu/imod/doc/man/dm2mrc.html +.. _newstack: https://bio3d.colorado.edu/doc/man/newstack.html diff --git a/docs/source/workflows/index.rst b/docs/source/workflows/index.rst index d8b36c39..f4f2c95b 100644 --- a/docs/source/workflows/index.rst +++ b/docs/source/workflows/index.rst @@ -7,3 +7,5 @@ Workflows .. _ref-workflow-spatial-omics: .. include:: spatialomics.rst + +.. include:: 2d_EM.rst From 6e972295e281fe3df4e32b3516b1f509d046eec7 Mon Sep 17 00:00:00 2001 From: Bradley Lowekamp Date: Mon, 29 Apr 2024 10:03:17 -0400 Subject: [PATCH 2/2] Document preserving 8-bit input dynamic range. --- docs/source/workflows/2d_EM.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/source/workflows/2d_EM.rst b/docs/source/workflows/2d_EM.rst index 0fb594b1..e62396ca 100644 --- a/docs/source/workflows/2d_EM.rst +++ b/docs/source/workflows/2d_EM.rst @@ -1,5 +1,5 @@ **** -2D Electron Microscopy Workflow ( formally known as DM conversion workflow) +2D Electron Microscopy Workflow ( formally known as DM conversion workflow ) **** Overview: @@ -43,6 +43,11 @@ Steps: .. code-block:: bash newstack -format TIFF -shrink $shrink_factor -antialias 6 -mode 0 -meansd "140,50" input.tiff output.tiff +Conditionals: + - if the input image size is less than the desired key image size, then `-shrink` and `-antialias` options are not + used. + - if the input pixel type is 8-bit, then the `-meadsd` option is not used. + The above command should convert any supported scalar pixel input type to an 8-bit image which a dynamic range reasonable for visualization. The `meansd` values could be considered tunable parameters. @@ -50,12 +55,12 @@ Output Generation +++++++++++++++++ The final step is to generate the thumbnail and key images with GraphicsMagick. The compression and filtering options -are used for web display. +are tuned for web display. Inputs: TIFF files Outputs: JPEG files Steps: - 1. Use GraphicsMagick to generate the thumbnail and key images. + 1. Use `GraphicsMagick`_ `convert`_ to generate the thumbnail and key images. .. code-block:: bash gm convert -size $output_size -resize $output_size -sharpen 2 -quality 80 input.tiff thumbnail.jpg @@ -69,3 +74,5 @@ further turned based on the input image. .. _IMOD: https://bio3d.colorado.edu/imod/ .. _dm2mrc: https://bio3d.colorado.edu/imod/doc/man/dm2mrc.html .. _newstack: https://bio3d.colorado.edu/doc/man/newstack.html +.. _GraphicsMagick: http://www.graphicsmagick.org/ +.. _convert: http://www.graphicsmagick.org/convert.html