~~NOTOC~~

===== sp_center_2d3d =====
Centering : Utility for centering in 2D or 3D.

\\
===== Usage =====

Usage in command line:

  sp_center_2d3d.py input_stack_or_volume output_directory --mode=centering_mode --verbosity=verbosity_level --debug --threshsigma=threshold_sigma --applyshift stack_or_volume_to_be_centered --ndilation=number_of_dilations --nerosion=number_of_erosions --volradius=volume_radius --dimensions=number_of_dimensions --stem=output_volume_prefix --threshint=intermediate_threshold --pad=padding_factor
  
  
\\
===== Typical usage =====
[{{ :pipeline:utilities:center2d.png?220|Left: uncentered binarized images, right: centered}}]
The purpose of sp_center_2d3d.py is to: 

  : center a stack of 2D images, or
  : center a 3D reconstruction

\\ __1. General usage__:

  sp_center_2d3d.py input_stack_or_volume output_directory

\\ __2. Center a stack of 2D images using an autocorrelation function__

  sp_center_2d3d.py input_stack output_directory --threshsigma=threshold_sigma 

Images will be thresholded in units of standard deviations above the mean. Check the output stkmask.hdf to see if the threshold is reasonable. 

\\ __3. Centering a stack by rotating each image by 180 degrees and aligning to itself__:

  sp_center_2d3d.py input_stack output_directory --mode=rt180
  
\\ __4. Center a binarized volume using an autocorrelation function__:

  sp_center_2d3d.py input_binary_volume output_directory --applyshift=volume_to_be_centered
  
Generate the input binary volume using, for example, [[pipeline:viper:sp_mask|sp_mask.py]]. An adaptive mask is fine also; it will be thresholded. The mask will be centered, and those shifts will be applied to the volume to be shifted.

\\ __5. Center a binarized volume by finding a box that encloses it and centering that box__:

  sp_center_2d3d.py input_binary_volume output_directory --mode=boundingbox --applyshift=volume_to_be_centered
  
As above, the input binary mask will be centered, and those shifts will be applied to the volume to be centered.

\\ __6. Center a volume by alignment to a Gaussian blob__:

  sp_center_2d3d.py volume_to_be_centered output_directory --mode=blob --volradius=volume_radius
  
If your volume to be centered isn't round, try the radius in the smallest dimension.

\\
===== Input =====
=== Main Parameters ===
  ; input_stack_or_volume : Can be a 3D volume, possibly binarized, or a stack of 2D images
  ; output_directory : Directory where outputs will be written. (default required string)
  ; %%--%%mode : Centering mode: acf, rt180, boundingbox, or blob. (default acf)
  ; %%--%%threshsigma : Binarization threshold in 2D acf mode, in units of standard deviation. (default 1.0)
  ; %%--%%applyshift : In 3D acf or boundingbox mode, volume to which shifts will be applied. (default None)
  ; %%--%%volradius : In blob mode, radius of the Gaussian blob, in voxels, to which the input map will be aligned. (default None)
  
\\
=== Advanced Parameters ===
  ; %%--%%verbosity : Writes additional information to the screen (0..3). (default 1)
  ; %%--%%debug : Writes additional outputs for debugging. (default False)
  ; %%--%%dimensions : In case it is ambiguous whether the input is 2D or 3D (e.g., MRC format), enter 2 or 3. (default 3)
  ; %%--%%threshint : In acf (2D or 3d) or boundingbox mode, threshold at which intermediates will be binarized. (default 0.1)
  ; %%--%%pad : In acf mode (2D or 3D), factor by which images will be padded. (default 2)
  ; %%--%%stem : In 3D acf mode, stem for output filenames. (default acf)
  ; %%--%%ndilation : In 2D acf mode, number of dilations (see sp_mask.py for more information). (default 3)[{{ :pipeline:utilities:center3d.png?400|Gray: uncentered map, violet: bounding box, melon: acf}}]
  ; %%--%%nerosion : In 2D acf mode, number of erosions (see sp_mask.py for more information). (default 0)

\\
===== Output =====
  ; stkmask_centered.hdf : In 2D acf mode, binarized images after centering
  ; stkavgs_centered.hdf : In 2D acf mode, input images after centering
  ; stkcompare.hdf : In 2D acf mode, montage of mask, centered image, and masked image
  ; stkcentered_rt180.hdf : In rt180 mode, input images after centering
  ; vol_acf_centered.hdf : In 3D acf mode, volume of interest after centering
  ; vol_blob_centered.hdf : In blob mode, volume of interest after centering
  ; vol_box_centered.hdf : In boundingbox mode, volume of interest after centering
  ; docshifts.txt : Shift parameters. Inputs will not be rotated.

\\

===== Description =====

\\
==== Method ====

\\
==== Reference ====

\\
==== Developer Notes ====

\\
==== Author / Maintainer ====
Tapu Shaikh

\\
==== Keywords ====
Category 1:: APPLICATIONS

\\
==== Files ====
sphire/bin/sp_center_2d3d.py

\\
==== See also ====

\\
==== Maturity ====
Beta:: Under evaluation and testing. Please let us know if there are any bugs.

\\
==== Bugs ====
There are no known bugs so far.

\\