xmipp3.protocols.protocol_shift_volume module
- class xmipp3.protocols.protocol_shift_volume.XmippProtShiftVolume(**kwargs)[source]
Bases:
EMProtocolShifts a 3D volume spatially according to user-provided parameters.
AI Generated
## Overview
The Shift Volume protocol translates a 3D volume by a user-defined or automatically determined shift.
This protocol is useful when a map needs to be recentered, moved consistently with a shifted particle set, or translated so that its center of mass is placed at the volume center. It does not perform rotational alignment or refinement. It only applies a spatial shift to a single input volume.
The shift can be obtained in three ways:
from a previous Shift particles protocol;
from user-provided X, Y, and Z shift values;
from the center of mass of the input volume.
The main output is a shifted volume. The protocol also outputs the X, Y, and Z shift values used.
## Inputs and General Workflow
The input is a single 3D volume.
The protocol first determines the shift values to apply. If requested, it reads the shift values from a previous Shift particles protocol. Otherwise, it uses manual X, Y, and Z values or computes a shift from the volume center of mass.
Optionally, the protocol first windows the input volume to a new box size. It then applies the selected shift using the Xmipp geometry transformation program.
Finally, it creates a new output volume and records the applied shift values.
## Input Volume
The Volume parameter defines the map to be shifted.
The input volume should be the volume that the user wants to translate. The original volume is not modified; the protocol writes a new shifted volume.
The output volume keeps the same sampling rate as the input volume.
## Use the Same Shifts as for the Particles
The Use the same shifts as for the particles? option tells the protocol to reuse the shift values produced by a previous Shift particles protocol.
This is useful when particles and volumes must be moved consistently. For example, if particles were recentered on a specific domain or region, the corresponding volume can be shifted by the same X, Y, and Z values so that both remain in the same coordinate convention.
When this option is enabled, the user must select the previous Shift particles protocol.
## Shift Particles Protocol
The Shift particles protocol parameter is used when the shift values are taken from a previous particle-shifting run.
The protocol reads the scalar outputs:
shiftX;
shiftY;
shiftZ.
These values are then applied to the input volume.
This option helps maintain consistency between a shifted particle set and a shifted reference or reconstruction volume.
## User-Defined Shift
If Use the same shifts as for the particles? is disabled and Use center of mass? is also disabled, the user provides the shift values manually.
The parameters are:
x;
y;
z.
These values define the translation applied to the volume.
Manual shifts are useful when the user already knows the desired displacement, for example from visual inspection, previous calculations, or external coordinate conventions.
## Use Center of Mass
The Use center of mass? option computes the shift automatically from the input volume.
In this mode, the protocol reads the volume, sets negative density values to zero, computes the center of mass of the remaining positive density, and chooses the shift that moves this center of mass toward the center of the box.
This is useful when the volume is off-center and the user wants to recenter it based on its density distribution.
This option assumes that the positive density corresponds to the structure of interest. If the map contains strong positive artifacts, disconnected density, or large background features, the center-of-mass shift may not represent the desired biological center.
## Box Size
The Use original box size for the shifted volume? option controls whether the output volume keeps the same box size as the input.
If enabled, the original box size is used.
If disabled, the protocol first applies a windowing operation to create a volume with the selected Final box size. The shift is then applied to that windowed volume.
Changing the box size can be useful when recentering a smaller region or when preparing a volume for a workflow that requires a specific box size.
## Final Box Size
The Final box size parameter is used when the original box size is not kept.
It defines the cubic box size of the intermediate windowed volume and therefore the size of the final shifted volume.
The value should be large enough to contain the shifted density. If the box is too small, relevant density may be cropped.
## Shift Application
The protocol applies the shift using xmipp_transform_geometry with the –shift option.
The transformation is performed with the –dont_wrap option. This means that density shifted outside the box is not wrapped around to the opposite side.
This behavior is usually appropriate for recentering, because wrapped density would create artificial features at the box boundaries.
## Output Volume
The main output is outputVolume.
This output is the shifted map written as shift_volume.mrc in the protocol working directory. It is registered as a Scipion volume and assigned the same sampling rate as the input volume.
The output can be used for visualization, comparison, refinement setup, or other workflows that require the map to be centered or shifted consistently.
## Shift Outputs
The protocol also produces three scalar outputs:
shiftX;
shiftY;
shiftZ.
These values record the translation applied to the volume.
They are useful for documentation, reproducibility, and for applying the same shift to related objects in later workflows.
## Interpretation of the Result
The output volume should be interpreted as the same density map translated in space.
No new structural information is created. The protocol does not refine, filter, mask, align, or validate the map. It only shifts the position of the density within the box.
If the selected shift is correct, the volume will be better centered or better matched to the coordinate convention required by downstream protocols. If the shift is incorrect, relevant density may become off-center or cropped.
## Practical Recommendations
Use the same shift as the particles when you need consistency between shifted particles and a corresponding volume.
Use manual X, Y, and Z values when the desired displacement is already known.
Use center-of-mass shifting for simple recentering, but inspect the result afterwards.
Be careful with maps containing large artifacts, disconnected components, or negative/positive density imbalance when using center of mass.
Keep the original box size unless there is a clear reason to change it.
If changing the box size, make sure the new box is large enough to contain the shifted structure.
Compare the shifted output with the original volume to confirm that the density has moved as expected.
## Final Perspective
Shift Volume is a simple volume-translation utility.
For biological users, its main value is practical coordinate control. It helps recenter maps, apply the same shifts used for particles, or prepare volumes for downstream protocols that expect a particular origin or density position.
The protocol should be understood as a geometrical transformation step. Its correctness depends on choosing shift values that match the intended coordinate frame and biological region.