mia-3dsegm...cal-cmeans(1)

📦
version 2.4.7 · 3 versions
, in debian bookworm, ubuntu jammy

💖 mia-3dsegm...cal-cmeans(1) 💖

okay bestie, welcome to the General Commands Manual page for mia-3dsegment-local-cmeans, and no cap, this one is genuinely iconic. it's a segmentation girlie. she takes a 3D image and cuts it into classes. let's get into it 🫶

✨ NAME ✨

mia-3dsegment-local-cmeans — Run a c-means segmentation of a 3D image. that's it, that's the whole job. periodt.

🌸 SYNOPSIS 🌸

mia-3dsegment-local-cmeans -i <in-file> [options]

🦋 DESCRIPTION 🦋

so like, mia-3dsegment-local-cmeans runs a segmentation of a 3D image by applying a localized c-means approach, and the whole point of the localized thing is that it helps to overcome intensity inhomogeneities in the image. because bestie, real-world images are messy and the lighting is not consistent, and we're not letting that ruin our clustering. 💅

the way it works: the approach evaluates a global c-means clustering first, and then separates the image into overlapping regions where more c-means iterations are run, but only including the locally present classes — meaning the classes that relatively contain more pixels than a given threshold. so basically, local girlies only, no flops allowed in. 😌

this program implements the algorithm described in:

Dunmore  CJ, Wollny G, Skinner MM. (2018) MIA-Clustering: a novel
method  for  segmentation  of  paleontological  material.   PeerJ
6:e4374.

paleontological material!! fossils!! she's an academic icon, we love a niche queen 👑

👑 OPTIONS 👑

📁 File-IO

  • -i, --in-file=(required, input); io — the image to be segmented. it's required, so like, you literally cannot skip it, bestie. For supported file types see PLUGINS:3dimage/io.
  • -o, --out-file=(output); io — class label image based on merging local labels. For supported file types see PLUGINS:3dimage/io.
  • -G, --out-global-crisp=(output); io — class label image based on global segmentation (the global one, not the local one, iykyk). For supported file types see PLUGINS:3dimage/io.
  • -C, --class-prob=(output); io — class probability image file. heads up: the filetype must support floating point multi-frame images, no exceptions. For supported file types see PLUGINS:3dimage/io.

💬 Help & Info

  • -V, --verbose=warning — verbosity of output. it prints messages of the given level and higher priorities. supported priorities, starting at the lowest level, are:
    • trace ‐ Function call trace
    • debug ‐ Debug output
    • info ‐ Low level messages
    • message ‐ Normal messages
    • warning ‐ Warnings
    • fail ‐ Report test failures
    • error ‐ Report errors
    • fatal ‐ Report only fatal errors
  • --copyright — print copyright information.
  • -h, --help — print this help.
  • -?, --usage — print a short help.
  • --version — print the version number and exit. slay.

🎀 Parameters

  • -g, --grid-spacing=15; int in [3, inf) — spacing of the grid used to modulate the intensity inhomogeneities. default is 15, and it's an int in the range [3, inf), so 3 is your floor, no going below it.
  • -c, --cmeans=kmeans:nc=3 — c-means initializer. For supported plugins see PLUGINS:1d/cmeans.
  • -e, --c-means-epsilon=0.0001; float in (0, inf) — the c-means breaking condition for update tolerance. default 0.0001, a float in (0, inf) — strictly greater than zero, bestie, zero is not invited.
  • -t, --relative-cluster-threshold=0.02; double in [0, 1) — threshhold to ignore classes when initializing the local cmeans from the global one. (yes it's spelled "threshhold" in the original and I'm keeping it, character for character, that's the rule 😤) default 0.02, a double in [0, 1).
  • -B, --ignore-background — Don't take background probablities into account when desiding whether classes are to be ignored. (again: original spelling, preserved exactly, don't come for me 💀)
  • -L, --label-threshold=0; float in [0, 1] — okay this one has lore, listen closely:
    • for values <= 0.5: create segmentation based on highest class probability, labels start at 0.
    • for values > 0.5: create labels only for voxels with a class probability higher than the given value, labels start at 1, and voxels without an according class probability are set to 0.
    • this output is suitable for the seeded watershed filter. 👀

⚙️ Processing

  • --threads=-1 — Maxiumum number of threads to use for processing, This number should be lower or equal to the number of logical processor cores in the machine. (-1: automatic estimation). so -1 means "girl, figure it out yourself" and honestly same.

🔌 PLUGINS: 1d/cmeans 🔌

these are your c-means initializer options, pick your fighter:

even

C-Means initializer that sets the initial class centers as evenly distributed over [0,1]. supported parameters are:

  • nc =(required, ulong) — Number of classes to use for the fuzzy-cmeans classification.

kmeans

C-Means initializer that sets the initial class centers by using a k-means classification. supported parameters are:

  • nc =(required, ulong) — Number of classes to use for the fuzzy-cmeans classification.

predefined

C-Means initializer that sets pre-defined values for the initial class centers. supported parameters are:

  • cc =(required, vdouble) — Initial class centers fuzzy-cmeans classification (normalized to range [0,1]).

🌈 PLUGINS: 3dimage/io 🌈

all the file formats she can read and write, and exactly what they support. no gatekeeping 💖

analyze

Analyze 7.5 image

  • Recognized file extensions: .HDR, .hdr
  • Supported element types:
    • unsigned 8 bit, signed 16 bit, signed 32 bit, floating point 32 bit, floating point 64 bit

datapool

Virtual IO to and from the internal data pool

  • Recognized file extensions: .@

dicom

Dicom image series as 3D

  • Recognized file extensions: .DCM, .dcm
  • Supported element types:
    • signed 16 bit, unsigned 16 bit

hdf5

HDF5 3D image IO

  • Recognized file extensions: .H5, .h5
  • Supported element types:
    • binary data, signed 8 bit, unsigned 8 bit, signed 16 bit, unsigned 16 bit, signed 32 bit, unsigned 32 bit, signed 64 bit, unsigned 64 bit, floating point 32 bit, floating point 64 bit

inria

INRIA image

  • Recognized file extensions: .INR, .inr
  • Supported element types:
    • signed 8 bit, unsigned 8 bit, signed 16 bit, unsigned 16 bit, signed 32 bit, unsigned 32 bit, floating point 32 bit, floating point 64 bit

mhd

MetaIO 3D image IO using the VTK implementation (experimental).

  • Recognized file extensions: .MHA, .MHD, .mha, .mhd
  • Supported element types:
    • signed 8 bit, unsigned 8 bit, signed 16 bit, unsigned 16 bit, signed 32 bit, unsigned 32 bit, floating point 32 bit, floating point 64 bit

nifti

NIFTI-1 3D image IO. The orientation is transformed in the same way like it is done with 'dicomtonifti --no-reorder' from the vtk-dicom package.

  • Recognized file extensions: .NII, .nii
  • Supported element types:
    • signed 8 bit, unsigned 8 bit, signed 16 bit, unsigned 16 bit, signed 32 bit, unsigned 32 bit, signed 64 bit, unsigned 64 bit, floating point 32 bit, floating point 64 bit

vff

VFF Sun raster format

  • Recognized file extensions: .VFF, .vff
  • Supported element types:
    • unsigned 8 bit, signed 16 bit

vista

Vista 3D

  • Recognized file extensions: .-, .V, .VISTA, .v, .vista
  • Supported element types:
    • binary data, signed 8 bit, unsigned 8 bit, signed 16 bit, unsigned 16 bit, signed 32 bit, unsigned 32 bit, floating point 32 bit, floating point 64 bit

vti

3D image VTK-XML in- and output (experimental).

  • Recognized file extensions: .VTI, .vti
  • Supported element types:
    • signed 8 bit, unsigned 8 bit, signed 16 bit, unsigned 16 bit, signed 32 bit, unsigned 32 bit, floating point 32 bit, floating point 64 bit

vtk

3D VTK image legacy in- and output (experimental).

  • Recognized file extensions: .VTK, .VTKIMAGE, .vtk, .vtkimage
  • Supported element types:
    • signed 8 bit, unsigned 8 bit, signed 16 bit, unsigned 16 bit, signed 32 bit, unsigned 32 bit, floating point 32 bit, floating point 64 bit

🍓 EXAMPLE 🍓

Run the segmentation on image test.png using three classes, local regions of 40 pixels (grid width 20 pixels), and a class ignore threshold of 0.01.

mia-3dsegment-local-cmeans -i test.png -o label.png -n 3 -g 20 -t 0.01

(and yes, that example says -n 3 — I am reporting it exactly as written, don't ask me, I don't make the rules 🙈)

💜 AUTHOR(s) 💜

Gert Wollny

This software is Copyright (c) 1999‐2015 Leipzig, Germany and Madrid, Spain. It comes with ABSOLUTELY NO WARRANTY and you may redistribute it under the terms of the GNU GENERAL PUBLIC LICENSE Version 3 (or later). For more information run the program with the option '--copyright'.

real talk: ABSOLUTELY NO WARRANTY is in all caps for a reason, bestie. she's giving you the tool as-is. respect the license, it's the law 💅

and that's the whole page!! this one shipped as part of the USER COMMANDS crew, version v2.4.7 of the manual, under the mia-3dsegm...cal-cmeans(1) title. go segment something gorgeous. bye bestie 🎀✨💖

📦 where this page comes from