↓ Skip to main content
HomCloud

NAME
#

pict.binarize_nd - Compute a persistence diagram from an N-dimensional picture by using a cubical dilation-erosion filtration of its binarization

SYNOPSIS
#

homcloud-pict-binarize-nd
    [-h] [-V] [-T TYPE] [-m MODE] [-t THRESHOLD]
    [--gt GT] [--lt LT] -o OUTPUT [-s] [--metric METRIC]
    [-C] [-p PERIODIC] [--mask MASK] [--algorithm ALGORITHM]
    [-M SAVE_BOUNDARY_MAP] [--license]
    [input ...]

This program can also be invoked as python3 -m homcloud.cli.pict.binarize_nd.

ALIAS
#

homcloud-pict-binarize-nd

DESCRIPTION
#

This program computes a persistence diagram from an N-dimensional picture by binarizing it and building a cubical dilation-erosion filtration.

The program accepts the following types of file formats: text2d, text_nd, picture2d, pictures3d and npy. If you want to know the details, please see the INPUT FILE FORMAT section below.

The input bitmap data is binarized by a given threshold (-t, or --gt/--lt for asymmetric bounds). After that a dilation-erosion filtration is constructed and a persistence diagram is computed and saved as a .pdgm file into OUTPUT.

If you want to flip the roles of black pixels and white pixels, please use the -m option.

By default the Manhattan distance is used to construct the dilation-erosion filtration. You can use other distances like Euclidean or Chebyshev with the --metric option.

-C/--cubical switches from the (fast, default) bitmap-based cubical filtration to an explicit cubical complex filtration, which is slower but is required by some downstream tools.

--mask lets you exclude part of the picture (pixels where the mask is nonzero are treated as an obstacle and are not used when enlarging the binarized region).

OPTIONS
#

-h, --help            show this help message and exit
-V, --version         show program's version number and exit
-T TYPE, --type TYPE  input data format
                      (text2d,text_nd(default),picture2d,pictures3d,npy)
-m MODE, --mode MODE  filtration type (black-base|white-base, default is
                      black-base)
-t THRESHOLD, --threshold THRESHOLD
                      threshold for binarization (default: 128)
--gt GT               lower threshold
--lt LT               upper threshold
-o OUTPUT, --output OUTPUT
                      output complex file name
-s, --ensmall         ensmall binarized picture
--metric METRIC       metric used to enlarge binarized image
                      (manhattan(default), euclidean, etc.)
-C, --cubical         use explicit cubical filtration (slow)
-p PERIODIC, --periodic PERIODIC
                      periodic (example: 0,1,1 for y and z are periodic)
--mask MASK           mask bitmap
--algorithm ALGORITHM
                      algorithm (dipha, phat-twist, phat-chunk-parallel)
-M SAVE_BOUNDARY_MAP, --save-boundary-map SAVE_BOUNDARY_MAP
                      save boundary map (yes/no, default:no)
--license             show license and exit

-M/--save-boundary-map requires -C/--cubical; giving -M on without -C is an error. Saving the boundary map is what makes the output usable later with homcloud-optvol.

INPUT FILE FORMAT
#

The program accepts the following types of file formats: text2d, text_nd, picture2d, pictures3d and npy.

text2d
#

2D pixel (floating point number) values represented by a text as follows:

x_11 x_12 ... x_1n
x_21 x_22 ... x_2n
 :    :        :
x_m1 x_m2 ... x_mn

Each coefficient should be floating point numbers. These values are binarized by the threshold value given by -t option.

text_nd
#

N-dimensional pixel (floating point number) values represented by a text as in the following format:

  • First line represents the shape of data. For example, if the shape of your data is 200x230x250, first line should be 200 230 250.
  • The following lines are floating point number values in x-fastest direction
  • A line starting with # is skipped as a comment
  • An empty line is also skipped.

An example is as follows:

# 4x3x2 3D voxel data
4 3 2

1 2 3 4
5 6 7 8
9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

picture2d
#

A gray scale PNG or TIFF file.

If the input file is 16bit grayscale file, the pixel value is normalized to the range of 0 .. 255.

pictures3d
#

Gray scale PNG or TIFF files. All picture sizes must be same. If not, an error occurs. All pictures are stacked in the commandline order.

If the input file is 16bit grayscale file, the pixel value is normalized to the range of 0 .. 255.

npy
#

Numpy’s npy file.

Please see https://docs.scipy.org/doc/numpy/neps/npy-format.html for details of this format.

OUTPUT FORMAT
#

The program always writes a .pdgm file into OUTPUT (a persistence diagram computed from the dilation-erosion filtration). Old output formats (.complex, .icomplex, .diagram, .idiagram) are no longer supported; giving OUTPUT one of these extensions raises an error.

NOTES
#

The old -I/--combine-index-map and -D/--convert-to-diagram options (used when the program produced dipha/idipha complex or diagram files) have been removed: the program always computes and writes a pdgm file directly now.