CZIcmd Documentation#

The console application “CZIcmd” is provided for two purposes: - demonstrate the usage of the libCZI - it might be useful to convert/extract data from a CZI-file

The synopsis of the program is:

Usage: CZIcmd.exe [OPTIONS]

using libCZI version 0.67.0

Options:

-h,–help Print this help message and exit

-c,–command COMMAND

COMMAND can be one of ‘PrintInformation’, ‘ExtractSubBlock’, ‘SingleChannelTileAccessor’, ‘ChannelComposite’, ‘SingleChannelPyramidTileAccessor’, ‘SingleChannelScalingTileAccessor’, ‘ScalingChannelComposite’, ‘ExtractAttachment’ and ‘CreateCZI’.

‘PrintInformation’ will print information about the CZI-file to the console. The argument ‘info-level’ can be used to specify which information is to be printed.

‘ExtractSubBlock’ will write the bitmap contained in the specified sub-block to the OUTPUTFILE.

‘ChannelComposite’ will create a channel-composite of the specified region and plane and apply display-settings to it. The resulting bitmap will be written to the specified OUTPUTFILE.

‘SingleChannelTileAccessor’ will create a tile-composite (only from sub-blocks on pyramid-layer 0) of the specified region and plane. The resulting bitmap will be written to the specified OUTPUTFILE.

‘SingleChannelPyramidTileAccessor’ adds to the previous command the ability to explicitly address a specific pyramid-layer (which must exist in the CZI-document).

‘SingleChannelScalingTileAccessor’ gets the specified region with an arbitrary zoom factor. It uses the pyramid-layers in the CZI-document and scales the bitmap if necessary. The resulting bitmap will be written to the specified OUTPUTFILE.

‘ScalingChannelComposite’ operates like the previous command, but in addition gets all channels and creates a multi-channel-composite from them using display-settings.

‘ExtractAttachment’ allows to extract (and save to a file) the contents of attachments.)

‘CreateCZI’ is used to demonstrate the CZI-creation capabilities of libCZI.)

‘PlaneScan’ does the following: over a ROI given with the –rect option a rectangle of size given with the –tilesize-for-plane-scan option is moved, and the image content of this rectangle is written out to files. The operation takes place on a plane which is given with the –plane-coordinate option. The filenames of the tile-bitmaps are generated from the filename given with the –output option, where a string _X[x-position]_Y[y-position]_W[width]_H[height] is added.

-s,–source SOURCEFILE

Specifies the source CZI-file.

--source-stream-class STREAMCLASS: Specifies the stream-class used for reading the source CZI-file. If not specified, the default file-reader stream-class is used. Run with argument ‘–version’ to get a list of available stream-classes.
--propbag-source-stream-creation PROPBAG: Specifies the property-bag used for creating the stream used for reading the source CZI-file. The data is given in JSON-notation.

-o,–output OUTPUTFILE: specifies the output-filename. A suffix will be appended to the name given here depending on the type of the file.
-p,–plane-coordinate PLANE-COORDINATE: Uniquely select a 2D-plane from the document. It is given in the form [DimChar][number], where ‘DimChar’ specifies a dimension and can be any of ‘Z’, ‘C’, ‘T’, ‘R’, ‘I’, ‘H’, ‘V’ or ‘B’. ‘number’ is an integer. Examples: C1T3, C0T-2, C1T44Z15H1.
-r,–rect ROI Select a paraxial rectangular region as the: region-of-interest. The coordinates may be given either absolute or relative. If using relative coordinates, they are relative to what is determined as the upper-left point in the document.nRelative coordinates are specified with the syntax ‘rel([x],[y],[width],[height])’, absolute coordinates are specified ‘abs([x],[y],[width],[height])’. Examples: rel(0, 0, 1024, 1024), rel(-100, -100, 500, 500), abs(-230, 100, 800, 800).
-d,–display-settings DISPLAYSETTINGS: Specifies the display-settings used for creating a channel-composite. The data is given in JSON-notation.

--calc-hash: Calculate a hash of the output-picture. The MD5Sum-algorithm is used for this.

-t,–drawtileboundaries: Draw a one-pixel black line around each tile.
-j,–jpgxrcodec DECODERNAME: Choose which decoder implementation is used. Specifying “WIC” will request the Windows-provided decoder - which is only available on Windows.By default the internal JPG-XR-decoder is used.
-v,–verbosity VERBOSITYLEVEL: Set the verbosity of this program. The argument is a comma- or semicolon-separated list of the following strings : ‘All’, ‘Errors’, ‘Warnings’, ‘Infos’, ‘Errors1’, ‘Warnings1’, ‘Infos1’, ‘Errors2’, ‘Warnings2’, ‘Infos2’.
-b,–background BACKGROUND: Specify the background color. BACKGROUND is either a single float or three floats, separated by a comma or semicolon. In case of a single float, it gives a grayscale value, in case of three floats it gives a RGB - value.The floats are given normalized to a range from 0 to 1.
-y,–pyramidinfo PYRAMIDINFO: For the command ‘SingleChannelPyramidTileAccessor’ the argument PYRAMIDINFO specifies the pyramid layer. It consists of two integers(separated by a comma, semicolon or pipe-symbol), where the first specifies the minification-factor (between pyramid-layers) and the second the pyramid-layer (starting with 0 for the layer with the highest resolution).
-z,–zoom ZOOM The zoom-factor (which is used for the commands: ‘SingleChannelScalingTileAccessor’ and ‘ScalingChannelComposite’). It is a float between 0 and 1.
-i,–info-level INFO-LEVEL: When using the command ‘PrintInformation’ the INFO-LEVEL can be used to specify which information is printed. Possible values are “Statistics”, “RawXML”, “DisplaySettings”, “DisplaySettingsJson”, “AllSubBlocks”, “Attachments”, “AllAttachments”, “PyramidStatistics”, “GeneralInfo”, “ScalingInfo” and “All”. The values are given as a list separated by comma or semicolon.
-e,–selection SELECTION: For the command ‘ExtractAttachment’ this allows to specify a subset which is to be extracted (and saved to a file). It is possible to specify the name and the index - only attachments for which the name/index is equal to those values specified are processed. The arguments are given in JSON-notation, e.g. {“name”:”Thumbnail”} or {“index”:3.0}.
-f,–tile-filter FILTER: Specify to filter subblocks according to the scene-index. A comma separated list of either an interval or a single integer may be given here, e.g. “2,3” or “2-4,6” or “0-3,5-8”.
-m,–channelcompositionformat CHANNELCOMPOSITIONFORMAT: In case of a channel-composition, specifies the pixeltype of the output. Possible values are “bgr24” (the default) and “bgra32”. If specifying “bgra32” it is possible to give the value of the alpha-pixels in the form “bgra32(128)” - for an alpha-value of 128.

--createbounds BOUNDS: Only used for ‘CreateCZI’: specify the range of coordinates used to create a CZI. Format is e.g. ‘T0:3Z0:3C0:2’.
--createsubblocksize SIZE: Only used for ‘CreateCZI’: specify the size of the subblocks created in pixels. Format is e.g. ‘1600x1200’.
--createtileinfo TILEINFO: Only used for ‘CreateCZI’: specify the number of tiles on each plane. Format is e.g. ‘3x3;10%’ for a 3 by 3 tiles arrangement with 10% overlap.

–font NAME/FILENAME: Only used for ‘CreateCZI’: (on Linux) specify the filename of a TrueType-font (.ttf) to be used for generating text in the subblocks; (on Windows) name of the font.

--fontheight HEIGHT: Only used for ‘CreateCZI’: specifies the height of the font in pixels (default: 36).

-g,–guidofczi CZI-File-GUID: Only used for ‘CreateCZI’: specify the GUID of the file (which is useful for bit-exact reproducible results); the GUID must be given in the form “cfc4a2fe-f968-4ef8-b685-e73d1b77271a” or “{cfc4a2fe-f968-4ef8-b685-e73d1b77271a}”

--bitmapgenerator BITMAPGENERATORCLASSNAME: Only used for ‘CreateCZI’: specifies the bitmap-generator to use. Possibly values are “gdi”, “freetype”, “null” or “default”. Run with argument ‘–version’ to get a list of available bitmap-generators.
--createczisbblkmetadata KEY_VALUE_SUBBLOCKMETADATA: Only used for ‘CreateCZI’: a key-value list in JSON-notation which will be written as subblock-metadata. For example: {“StageXPosition”:-8906.346,”StageYPosition”:-648.51}
--compressionopts COMPRESSIONDESCRIPTION: Only used for ‘CreateCZI’: a string in a defined format which states the compression-method and (compression-method specific) parameters.The format is “compression_method: key=value; …”. It starts with the name of the compression-method, followed by a colon, then followed by a list of key-value pairs which are separated by a semicolon. Examples: “zstd0:ExplicitLevel=3”, “zstd1:ExplicitLevel=2;PreProcess=HiLoByteUnpack”.
--generatorpixeltype PIXELTYPE: Only used for ‘CreateCZI’: a string defining the pixeltype used by the bitmap - generator. Possible values are ‘Gray8’, ‘Gray16’, ‘Bgr24’ or ‘Bgr48’. Default is ‘Bgr24’.
--cachesize CACHESIZE: Only used for ‘PlaneScan’ - specify the size of the subblock-cache in bytes. The argument is to be given with a suffix k, M, G, …
--tilesize-for-plane-scan TILESIZE: Only used for ‘PlaneScan’ - specify the size of ROI which is used for scanning the plane in units of pixels. Format is e.g. ‘1600x1200’ and default is 512x512.
--use-visibility-check-optimization: Whether to enable the experimental “visibility check optimization” for the accessors.
--mask-aware-compositing: Whether to use mask-aware compositing. This is subject to the availability of mask data in the CZI-file.
--version: Print extended version-info and supported operations, then exit.

The above text is printed if the program is executed with the argument ‘-?’ or ‘--help’:

CZIcmd --help

The program expects the argument ‘-c’ or ‘--command’ in order to select between different operations. The command choosen then determines which other arguments have to be given for proper operation or are meaningful.

command ‘PrintInformation’#

If the command ‘PrintInformation’ is specified, the program expects a source CZI-file to present (specified with ‘-s’ or ‘--source’). It will then print out some information about the content of the CZI-file on stdout - as shown here:

CZIcmd.exe --command PrintInformation --source D:\PICTURES\Example_TMA1_Zeb1_SPRR2_Ck19_S100-1-1-1-1.czi

SubBlock-Statistics
-------------------

SubBlock - Count: 122720

Bounding-Box:
 X=0 Y=0 W=139756 H=103036

M-Index: min=0 max=140

Bounds:
 C -> Start=0 Size=4
 T -> Start=0 Size=1
 S -> Start=0 Size=22
 B -> Start=0 Size=1

Bounding-Box for scenes:
 Scene0 : X=23894 Y=1840 W=22240 H=18592
 Scene1 : X=2 Y=0 W=22240 H=24096
 Scene2 : X=47755 Y=3676 W=18592 H=18592
 Scene3 : X=71630 Y=3676 W=24096 H=22240
 Scene4 : X=97334 Y=5512 W=22240 H=20416
 Scene5 : X=22058 Y=25708 W=24096 H=20416
 Scene6 : X=13 Y=27544 W=20416 H=20416
 Scene7 : X=66122 Y=27544 W=25920 H=22240
 Scene8 : X=47762 Y=33052 W=16736 H=14912
 Scene9 : X=93662 Y=29380 W=25920 H=22240
 Scene10 : X=119361 Y=31216 W=20416 H=20416
 Scene11 : X=22058 Y=49576 W=22240 H=24096
 Scene12 : X=0 Y=51412 W=20416 H=22241
 Scene13 : X=45922 Y=51412 W=24096 H=24096
 Scene14 : X=67958 Y=51412 W=24096 H=25920
 Scene15 : X=91808 Y=53248 W=25945 H=22240
 Scene16 : X=117524 Y=55084 W=20416 H=25920
 Scene17 : X=26 Y=75280 W=20416 H=20420
 Scene18 : X=22058 Y=75280 W=24096 H=24096
 Scene19 : X=45926 Y=77116 W=22240 H=20416
 Scene20 : X=67958 Y=77116 W=20416 H=22240
 Scene21 : X=89976 Y=78952 W=24096 H=22240
 Scene22 : X=115693 Y=82624 W=20416 H=20416

The argument ‘-i’ or ‘--info-level’ is used to choose between different types of output (where only “Statistics” is default). So we get additional information about the display-settings by running this command:

CZIcmd.exe --info-level PyramidStatistics  --command PrintInformation --source D:\PICTURES\NaCZIrTestData\Example_TMA1_Zeb1_SPRR2_Ck19_S100-1-1-1-1.czi

Pyramid-Subblock-Statistics
---------------------------

scene#0:
 number of subblocks with scale 1/32: 5
 number of subblocks with scale 1/16: 20
 number of subblocks with scale 1/8: 45
 number of subblocks with scale 1/4: 140
 number of subblocks with scale 1/2: 505
 number of subblocks with scale 1/1: 485

scene#1:
 number of subblocks with scale 1/32: 5
 number of subblocks with scale 1/16: 20
 number of subblocks with scale 1/8: 45
 number of subblocks with scale 1/4: 165
 number of subblocks with scale 1/2: 600
 number of subblocks with scale 1/1: 630

scene#2:
 number of subblocks with scale 1/32: 5
 number of subblocks with scale 1/16: 15
 number of subblocks with scale 1/8: 40
 number of subblocks with scale 1/4: 120
 number of subblocks with scale 1/2: 415
 number of subblocks with scale 1/1: 355

scene#3:
 number of subblocks with scale 1/32: 5
 number of subblocks with scale 1/16: 20
 number of subblocks with scale 1/8: 45
 number of subblocks with scale 1/4: 160
 number of subblocks with scale 1/2: 595
 number of subblocks with scale 1/1: 640

scene#4:
 number of subblocks with scale 1/32: 5
 number of subblocks with scale 1/16: 20
 number of subblocks with scale 1/8: 45
 number of subblocks with scale 1/4: 140
 number of subblocks with scale 1/2: 525
 number of subblocks with scale 1/1: 540

scene#5:
 number of subblocks with scale 1/32: 5
 number of subblocks with scale 1/16: 20
 number of subblocks with scale 1/8: 45

If ‘RawXML’ is specified as argument for ‘-i’ or ‘--info-level’, the complete metadata is written to stdout as XML.

‘DisplaySettingsJson’ will output the display-settings in JSON-notation as it is used in CZICmd.

CZIcmd.exe --info-level DisplaySettingsJson  --command PrintInformation --source D:\PICTURES\NaCZIrTestData\Example_TMA1_Zeb1_SPRR2_Ck19_S100-1-1-1-1.czi

Display-Settings in CZIcmd-JSON-Format
--------------------------------------


Pretty-Print:
{
        "channels": [
                {
                        "ch": 0,
                        "black-point": 0.00007820712198736146,
                        "white-point": 0.01801724173128605,
                        "tinting": "#0000ff"
                },
                {
                        "ch": 1,
                        "black-point": 0.0,
                        "white-point": 0.8125027418136597,
                        "tinting": "#ff0000"
                },
                {
                        "ch": 2,
                        "black-point": 0.00007992737664608285,
                        "white-point": 0.570344865322113,
                        "tinting": "#00ff00"
                },
                {
                        "ch": 3,
                        "black-point": 0.00007992124301381409,
                        "white-point": 0.7000391483306885,
                        "tinting": "#ffff00"
                },
                {
                        "ch": 4,
                        "black-point": 0.00007971125887706876,
                        "white-point": 0.2200983464717865,
                        "tinting": "#00ffff"
                }
        ]
}

Compact:
{"channels":[{"ch":0,"black-point":0.00007820712198736146,"white-point":0.018017
24173128605,"tinting":"#0000ff"},{"ch":1,"black-point":0.0,"white-point":0.81250
27418136597,"tinting":"#ff0000"},{"ch":2,"black-point":0.00007992737664608285,"w
hite-point":0.570344865322113,"tinting":"#00ff00"},{"ch":3,"black-point":0.00007
992124301381409,"white-point":0.7000391483306885,"tinting":"#ffff00"},{"ch":4,"b
lack-point":0.00007971125887706876,"white-point":0.2200983464717865,"tinting":"#
00ffff"}]}

‘Attachments’ and ‘AllAttachments’ are used to get information about the attachments contained in the CZI-file:

CZIcmd.exe --info-level Attachments  --command PrintInformation --source D:\PICTURES\NaCZIrTestData\Example_TMA1_Zeb1_SPRR2_Ck19_S100-1-1-1-1.czi

 Attachment Info
 ---------------

 count | name
 ------+----------------------------
     1 | EventList
     1 | Label
     1 | SlidePreview
     1 | Thumbnail
     1 | TimeStamps

In this case we get a list of the attachments present in the file, aggregated by their name (and how many times an attachment with a specific name is present).

CZIcmd.exe --info-level AllAttachments  --command PrintInformation --source D:\PICTURES\NaCZIrTestData\Example_TMA1_Zeb1_SPRR2_Ck19_S100-1-1-1-1.czi

Complete list of Attachments#
index	filetype	GUID	name
0	CZTIMS	{D2FD4125-CBF0-4B27-A8F2-643EDC5BAE7B}	TimeStamps
1	CZEVL	{725AE927-5D00-4EBC-BB61-9362207F1B5D}	EventList
2	CZI	{45165480-EEB9-417E-BC72-877E9A37EDAE}	Label
3	CZI	{DD9A366F-4941-45B9-94FD-6043B1B96C16}	SlidePreview
4	JPG	{7B25A072-7E33-4D2B-8921-DE69D09A3127}	Thumbnail

Here we get the complete list of all attachments.

command ‘SingleChannelTileAccessor’#

The command ‘SingleChannelTileAccessor’ will use an accessor of type SingleChannelTileAccessor (cf. [accessors](accessors.markdown)). It will use the argument ‘-p’ or ‘--plane-coordinate’ in order to specify the plane, and the argument ‘-r’ or ‘--rect’ in order to specify a rectangular (and axis-aligned) region (or ROI). The pixel-type of the output is determined automatically (cf. [ISingleChannelTileAccessor](@ref libCZI::ISingleChannelTileAccessor)).

The following sample will extract the ROI (x=21300,y=21000,w=4096,h=4096) from channel #0

CZIcmd.exe --command SingleChannelTileAccessor --plane-coordinate C0 --rect rel(21300,21000,4096,4096) --source D:\PICTURES\2014_02_05__16_39__0020-2.czi --output d:\PICTURES\Out\Output_2014_02_05__16_39__0020-2

and write out the result to a PNG-file with name d:PICTURESOutOutput_2014_02_05__16_39__0020-2.PNG.

The following arguments are meaningful for this command:

‘-p’ or ‘--plane-coordinate’
‘-r’ or ‘--rect’
‘-j’ or ‘--jpgxrcodec’
‘-b’ or ‘--background’

command ‘ChannelComposite’#

The command ‘ChannelComposite’ operates similar to ‘SingleChannelTileAccessor’, but in addition gathers the tile-composites from all channels, applies display-settings and creates a multi-channel-composite. Therefore, the argument to ‘--plane-coordinate’ does not contain a C-coordinate (all channels which are marked ‘active’ in the display-settings will be processed). The display-settings are either given on the commandline with the argument ‘-d’ or ‘--display-settings’, or if this argument is not given, then they are retrieved from the CZI-document’s metadata.

The following sample will create a PNG-file (with name d:PICTURESOutOutput_DCV_30MB.PNG) just like in the ZEN-2D-viewer (using the display-settings from the CZI-file):

CZIcmd.exe --command ChannelComposite --plane-coordinate Z10 --rect rel(0,0,512,512)  --source D:\PICTURES\DCV_30MB.czi --output d:\PICTURES\Out\Output_DCV_30MB

The following arguments are meaningful for this command:

‘-p’ or ‘--plane-coordinate’
‘-r’ or ‘--rect’
‘-j’ or ‘--jpgxrcodec’
‘-b’ or ‘--background’
‘-d’ or ‘--display-settings’
‘-f’ or ‘--tile-filter’

In order to specify the display-settings on the commandline, a JSON-notation is used - an example is shown here:

{
  "channels": [
        {
          "ch": 0,
          "tinting": "#41ff00",
          "weight": 1,
          "black-point": 0,
          "white-point": 0.15259021896696423
        },
        {
          "ch": 1,
          "tinting": "#ffd200",
          "weight": 1,
          "black-point": 0,
          "white-point": 0.15259021896696423
        },
        {
          "ch": 2,
          "tinting": "#4178ff",
          "weight": 1,
          "black-point": 0,
          "white-point": 0.15259021896696423
        }
  ]
}

It is an array “channels”, where the following fields are possible:

Channel Fields#
field name	type	explanation
ch	integer	the channel-index for which this channel-display-settings applies to
black-point	number	the black-point (default: 0)
white-point	number	the white-point (default: 1)
tinting	string	gives the RGB24-color as a 6-digit hexadecimal number, must start with a hash (‘#’)
gamma	number	the gradation curve is defined by a gamma with the value given here
splinelut	array of numbers	the gradation curve is defined a spline, and the list of numbers are the x and y coordinates of the control-points of a spline

Note that ‘gamma’ and ‘splinelut’ are mutually exclusive, if both happen to be present, then ‘gamma’ takes precedence.

An example for a display-setting when specifying a spline is:

{
  "channels": [
        {
          "ch": 0,
          "splinelut": [
                0.362559241706161,      0.876190476190476,
                0.554502369668246,      0.561904761904762
          ]
        }
  ]
}

Note that it is a flat list of numbers, where the first number is interpreted as X and the second as Y - and so on.

Passing this JSON on the commandline might be challenging, though - because many characters need to be escaped (depending on your command shell).

command ‘ExtractAttachment’#

The command ‘ExtractAttachment’ allows to extract attachments and save them to a distinct file.

CZIcmd.exe --command ExtractAttachment --source D:\PICTURES\NaCZIrTestData\Example_TMA1_Zeb1_SPRR2_Ck19_S100-1-1-1-1.czi --output attachments

dir

 Volume in drive D is DATA
 Volume Serial Number is 74F9-A4A3

 Directory of D:\TFSJBL\LibCZIDistrib\Src\Build\VS\Win32\Release\out

05/11/2016  12:56 PM    <DIR>          .
05/11/2016  12:56 PM    <DIR>          ..
05/11/2016  12:56 PM               158 attachments_EventList_1.CZEVL
05/11/2016  12:56 PM         2,887,520 attachments_Label_2.CZI
05/11/2016  12:56 PM         6,744,768 attachments_SlidePreview_3.CZI
05/11/2016  12:56 PM             3,904 attachments_Thumbnail_4.JPG
05/11/2016  12:56 PM                16 attachments_TimeStamps_0.CZTIMS
                           5 File(s)      9,636,366 bytes
                           2 Dir(s)  519,149,056,000 bytes free

The filename of the attachments is composed from the --output-argument, appending the name of the attachment and its id. The extension is given by the ‘filetype’-field of the attachment.

In the above example, all attachments are processed. It is possible to filter the attachments - by giving the name or the index. This is specified with the --selection-argument:

CZIcmd.exe --command ExtractAttachment --source D:\PICTURES\NaCZIrTestData\Example_TMA1_Zeb1_SPRR2_Ck19_S100-1-1-1-1.czi --output attachments --selection {\"name\":\"Thumbnail\"}

This will only save the attachments with ‘name’ = “Thumbnail”.

CZIcmd.exe --command ExtractAttachment --source D:\PICTURES\NaCZIrTestData\Example_TMA1_Zeb1_SPRR2_Ck19_S100-1-1-1-1.czi --output attachments --selection {\"index\":1.0}

This will only save the attachments with id = 1.

CZIcmd Documentation

Contents

CZIcmd Documentation#

command ‘PrintInformation’#

command ‘SingleChannelTileAccessor’#

command ‘ChannelComposite’#

command ‘ExtractAttachment’#