demeter.metamorphosis package

Submodules

demeter.metamorphosis.abstract module

The implementation of Metamorphoses in Demeter is based on the minimization of a Hamiltonian:

\[H(q,p,v,z) = (p|\dot q) - R(v,z)\]

where \(q : (\Omega, [0,1]) \mapsto \mathcal M\) is the temporal image valued in \(\mathcal M\), \(R\) is a regularization function, \(v\) is a vector field, and \(z\) is a control on the photometric part.

In the case of LDDMM and considering \(\mathcal M = \mathbb R\), the Hamiltonian is:

\[H(q,p,v,z) = (p|\dot q) - \frac 12\|v\|_V^2 - \frac 12\|z\|_Z^2\]

An optimal trajectory or geodesic under the conditions given by \(H\) is:

\[\begin{split}\left\{\begin{array}{rl} \dot q_t &= - \nabla q_t \cdot v_t + z_t\\ \dot z_t &= - \mathrm{div}(z_t v_t) \\ p_t &= z_t\\ v_t &= -K_V\left( z_t\nabla q_t \right) \end{array}\right.\end{split}\]

These equations are written in the continuous case. In this document, all discretization choices made during the implementation are detailed.

To solve the registration problem, a geodesic shooting strategy is used. For this, a relaxed version of \(H\) is minimized:

\[E(p_0) = D_T(I_1) + \frac{\lambda}{2} \left( \|v_0\|_V^2 +\|z_0\|_Z^2 \right)\]

Where \(D_T\) is a data attachment term and \(T\) is a target image, \(I_1\) is the image at the end of the geodesic integration, and \(p_0\) is the initial momentum. Note that in the case of Metamorphoses valued in images, \(p = z\).

You may have noticed that in the above equation \(E(p_{0})\) depends only on the initial momentum. Indeed, thanks to a conservation property of norms during the calculation of optimal trajectories in a Hamiltonian which states: Let \(v\) and \(z\) follow a geodesic given by \(H\), then

\[\forall t \in [0,1], \|v_{0}\|^2_{V} = \|v_{t}\|^2_{V}; \|v_{0}\|^2_{2} = \|z_{t}\|^2_{2}. \]

This property is used to save computation time. In practice, due to numerical scheme choices, norm conservation may not be achieved. In this case, it is possible to optimize over the set of norms and \(E\) becomes:

\[E(p_0) = D_T(I_1) + \frac \lambda2 \int_{0}^1 \left( \|v_t\|_V^2 +\|z_t\|_Z^2 \right) dt.\]

The \(I_{t},v_t,z_{t}\) are still deduced from \(p_0\). It is possible to switch between the two in the code using the hamiltonian_integration option in the children of Optimize_geodesicShooting.

class demeter.metamorphosis.abstract.Geodesic_integrator(kernelOperator, n_step, dx_convention='pixel', **kwargs)

Bases: Module, ABC

The Geodesic_integrator class is an abstract class that inherits from torch.nn.Module and ABC (Abstract Base Class). It is designed to define the way of integrating geodesics in the context of metamorphosis optimization. If you want to implement a new geodesic integrator, you inherit from this class and implement the abstract methods, with a focus on the step method which contains the code numerical scheme for a step of the geodesic integration.

Here are the main features of the class:

  • Initialization:

    The constructor initializes the basic parameters needed for geodesic integration, such as the kernel operator (kernelOperator),

    the number of steps (n_step), and the spatial differentiation convention

    (dx_convention).

  • Abstract Methods:

    The class contains abstract methods like step, which must be implemented by derived classes to define the specific steps of the integration.

  • Temporal Integration:

    The forward method performs the temporal loop using the appropriate _step_ method to integrate the source image along the geodesic.

  • Generic functions useful for integration:

    Methods _compute_vectorField_, _update_image_semiLagrangian_ ot _compute_vectorField_multimodal_ implements updates of the field, the momentum and the image.

  • Plots and Visualization:

    The class includes methods for visualizing the integration results, such as plot, plot_deform, and save_to_gif.

Note

The integrated plot and visualization methods are implemented for 2d images only. If you want to use them for 3d images, you need to use

others functions like the ones in image_3d_visualization.py.

Parameters:

  • kernelOperator (reproducing_kernel.ReproducingKernel) – The kernel operator used to compute the vector field.

  • n_step (int) – The number of steps for the geodesic integration.

  • dx_convention (str, optional) – The spatial differentiation convention, by default “pixel”.

forward(image, momentum_ini, save=True, plot=0, t_max=1, verbose=False, sharp=None, debug=False, hamiltonian_integration=False)

This method is doing the temporal loop using the good method _step_

Parameters:

  • image (tensor array of shape [1,1,H,W]) – Source image (\(I_0\))

  • momentum_ini (tensor array of shape [1,1,H,W]) – Momentum (\(p_0\)) or residual (\(z_0\))

  • save (bool, optional) – Option to save the integration intermediary steps, by default True it saves the image, field and momentum at each step in the attributes image_stock, field_stock and momentum_stock.

  • plot (int, optional) – Positive int lower than self.n_step to plot the indicated number of intermediary steps, by default 0

  • t_max (int, optional) – The integration will be made on [0,t_max], by default 1

  • verbose (bool, optional) – Option to print the progress of the integration, by default False

  • sharp (bool, optional) – Option to use the sharp integration, by default None

  • debug (bool, optional) – Option to print debug information, by default False

  • hamiltonian_integration (bool, optional) –

    Choose to integrate over first time step only or whole hamiltonian, in practice when True, the Regulation norms of the Hamiltonian are computed and saved in the good attributes (usually norm_v and norm_z),

    by default False

get_deformation(from_t=0, to_t=None, save=False)

Returns the deformation use it for showing results \(\Phi = \int_s^t v_t dt\) with \(s < t\) and \(t \in [0,n_{step}-1]\)

Params:

from_t : (int) the starting time step (default 0)

Params:

to_t : (int) the ending time step (default n_step)

Params:

save : (bool) option to save the integration intermediary steps. If true, the return value will have its shape with T>1

Returns:

deformation [T,H,W,2] or [T,H,W,D,3]

get_deformator(from_t=0, to_t=None, save=False)

Returns the inverse deformation use it for deforming images \((\Phi_{s,t})^{-1}\) with \(s < t\) and \(t \in [0,n_{step}-1]\)

Params:

from_t : (int) the starting time step (default 0)

Params:

to_t : (int) the ending time step (default n_step)

Params:

save : (bool) option to save the integration intermediary steps. If true, the return value will have its shape with T>1

Returns:

deformation [T,H,W,2] or [T,H,W,D,3]

plot(n_figs=5)
plot_deform(target, temporal_nfig=0)
abstractmethod step()
to_device(device)
class demeter.metamorphosis.abstract.Optimize_geodesicShooting(source: Tensor, target: Tensor, geodesic: Geodesic_integrator, cost_cst, data_term=None, optimizer_method: str = 'grad_descent', hamiltonian_integration=False, **kwargs)

Bases: Module, ABC

Abstract method for geodesic shooting optimisation. It needs to be provided with an object inheriting from Geodesic_integrator

compute_DICE(source_segmentation, target_segmentation, plot=False, forward=True)

Compute the DICE score of a regristration. Given the segmentations of a structure (ex: ventricules) that should be present in both source and target image. it gives a score close to one if the segmentations are well matching after transformation.

Parameters:

  • source_segmentation – Tensor of source size?

  • target_segmentation

Returns:

(float) DICE score.

compute_landmark_dist(source_landmark, target_landmark=None, forward=True, verbose=True, round=False)
abstractmethod cost(residual_ini)
forward(**kwargs)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

forward_safe_mode(z_0, n_iter=10, grad_coef=0.001, verbose=True, mode=None)

Same as Optimize_geodesicShooting.forward(…) but does not stop the program when the integration diverges. If mode is not None, it tries to change the parameter until convergence as described in `mode`

Parameters:

z_0 – initial residual. It is the variable on which we optimize.

require_grad must be set to True. :param n_iter: (int) number of optimizer iterations :param verbose: (bool) display advancement :param mode:

‘grad_coef’ this mode will decrease the grad_coef by dividing it by 10.

Returns:

get_DICE()
abstractmethod get_all_arguments()
get_geodesic_distance(only_zero=False)
get_landmark_dist()
get_ssd_def()
get_total_cost()
plot(y_log=False)
plot_cost(y_log=False)

To display the evolution of cost during the optimisation.

plot_deform(temporal_nfigs=0)

Display the deformation of the source image to the target image and the source image deformed by the deformation field.

plot_imgCmp()

Display and compare the deformed image \(I_1\) with the target$

save(file_name, save_path=None, light_save=False, message=None, destination=None, file_csv=None, add_location_to_file=True)

Save an optimisation to be later loaded and write all sort of info in a csv file

Parameters:

file_namestr

will appear in the file name

save_pathstr

Path where to save the optimisation. by default the saving location is given by the constant : OPTIM_SAVE_DIR. You can change it in your environment (file .env)

light_savebool

if True, only the initial momentum is saved. If False all data, integration, source and target are saved. Setting it to True save a lot of space on the disk, but you might not be able to get the whole registration back if the source image is different or the code used for computing it changed for any reason.

messagestr

will appear in the csv storing all data

destinationstr

path of the folder to store the csvfile overview

file_csvstr

name of the csv file to store the overview of the saved optimisation default is ‘saved_optim/saves_overview.csv’

add_location_to_filebool

add home name in saved file to track on which computer it has been computed. (default True)

Note

Demeter allows you to save registration results as metamorphosis objects to be able to reuse, restart, visualize, or analyze the results later. By default, we store them in the ~/.local/share/Demeter_metamorphosis/ folder on linux (may wary on other platforms). You can change the default location by setting the DEMETER_OPTIM_SAVE_DIR environment variable. in the .env file. To locate it you can use the following commands: (in a python file or in a ipython terminal)

demeter.display_env_help()

Returns:

file_save,

name of the file saved

path

path of the file saved

save_to_gif(object, file_name, folder=None, delay=40, clean=True)

Save a gif of the optimisation. The object must be a string containing at least one of the following : image,`residual`,`deformation`.

Parameters:

  • object – str can be a string containing at least one of the following : image,`residual`,`deformation`. or a combination of them.

  • file_name – str name of the file to save

  • folder – str path of the folder to save the gif

  • delay – int delay between each frame in the gif

  • clean – bool if True, the images used to create the gif are deleted.

to_device(device)

demeter.metamorphosis.classic module

This module contains the classical Metamorphosis algorithm. Defined as follows:

We define the Hamiltonian:

\[H(I,p,v,z) = - (p |\dot{ I}) - \frac{1}{2} (Lv|v)_{2} - \frac{1}{2}(z,z)_{2}.\]

By calculating the optimal trajectories we obtain the system:

\[\begin{split}\left\{ \begin{array}{rl} v &= - \sqrt{ \rho } K_{V} (p \nabla I)\\ \dot{p} &= -\sqrt{ \rho } \nabla \cdot (pv) \\ z &= \sqrt{ 1 - \rho } p \\ \dot{I} &= - \sqrt{ \rho } v_{t} \cdot \nabla I_{t} + \sqrt{ 1-\rho } z.\end{array} \right.\end{split}\]

In practice we minimize the Energy function:

\[E(p_0) = D(I_1,T) + \lambda \Big[ \|v_0\|^2_V + \|z_0\|^2_{L_2} \Big]\]

with \(D(I_1,T)\) the data term given by the user, \(\|v_0\|^2_V = (Lv,v)_2\) the RKHS norm of the velocity field parametrized by L^{-1} = K_\sigma$ that we call the kernel operator and \(\|z_0\|^2_{L_2}\) the \(L_2\) norm of the momentum field.

class demeter.metamorphosis.classic.Metamorphosis_Shooting(source, target, geodesic, **kwargs)

Bases: Optimize_geodesicShooting

Metamorphosis shooting class, implements the shooting algorithm for metamorphosis over the energy function:

\[E(p_0) = D( I_1,T) + \lambda \Big[ \|v_0\|^2_V + \mu ^2 \|z_0\|^2_{L_2} \Big]\]
with:

  • \(D(I_1,T)\) the data term given by the user.

  • I_1 is obtained by integrating the geodesics over the geodesic equation using the provided integrator class.

  • \(\|v_0\|^2_V = (Lv,v)_2\) the RKHS norm of the velocity field parametrized by L^{-1} = K_sigma$ that we call the kernel operator

  • \(\|z_0\|^2_{L_2} =\frac{1}{\# \Omega} \sum z_0^2\) the \(L_2\) norm of the momentum field, with \(\# \Omega\) the number of pixels in the image.

Parameters:

  • source (torch.Tensor) – source image

  • target (torch.Tensor) – target image

  • geodesic (Metamorphosis_integrator) – geodesic integrator

  • cost_cst (float) – cost constant

  • data_term (mt.DataCost, optional) – data term, by default Ssd

  • optimizer_method (str, optional) – optimizer method, by default ‘LBFGS_torch’

  • hamiltonian_integration (bool, optional) –

    choose to integrate over first time step only or whole hamiltonian

    integration, by default False

cost(momentum_ini: Tensor) → Tensor

cost computation

Parameters:

momentum_ini – Moment initial p_0

Returns:

\(H(z_0)\) a single valued tensor

get_all_arguments()
class demeter.metamorphosis.classic.Metamorphosis_integrator(method, rho=1.0, **kwargs)

Bases: Geodesic_integrator

Class integrating over a geodesic shooting. The user can choose the method among ‘Eulerian’, ‘advection_semiLagrangian’ and ‘semiLagrangian.

Parameters:

  • rho – (float) \(\rho \in [0,1]\) Control parameter for geodesic shooting intensities changes \(rho = 1\) is LDDMM \(mu = 0\) is pure photomeric changes and any value in between is a mix of both.

  • sigma_v – sigma of the gaussian RKHS in the V norm

  • n_step – number of time step in the segment [0,1] over the geodesic integration

step()

demeter.metamorphosis.constrained module

This module contains the classes for the constrained metamorphosis framework. The constrained metamorphosis framework is a generalisation of the metamorphosis framework that allows to add two types of constraints: - One on the residual by controlling locally the amount of deformation versus the amount of photometric changes at given pixels. - One on the field by adding a prior orienting field that will guide the deformation.

class demeter.metamorphosis.constrained.ConstrainedMetamorphosis_Shooting(source, target, geodesic, cost_cst, data_term=None, optimizer_method='adadelta', **kwargs)

Bases: Optimize_geodesicShooting

This class is an extension of the Optimize_geodesicShooting class. It allows to optimise a geodesic with constraints on the residual and the field using prior masks and fields.

It implements and optiimise over the following cost function:

\[H(I,p,v,z) = D(I_1,T) - \frac{1}{2} (Lv|v)_{2} - \frac{1}{2}|z|_{2} - \langle v,Qw\rangle_{2}. \]

with:

  • \(D(I_1,T)\) the data term given by the user.

  • I_1 is obtained by integrating the geodesics over the geodesic equation using the provided integrator class.

  • \(\|v_0\|^2_V = (Lv,v)_2\) the RKHS norm of the velocity field parametrized by $L^{-1} = K_sigma$ that we call the kernel operator

  • \(\|z_0\|^2_{L_2} =\frac{1}{\# \Omega} \sum z_0^2\) the \(L_2\) norm of the momentum field, with \(\# \Omega\) the number of pixels in the image.

  • \(\langle v,Qw\rangle_{2} = \frac{1}{\# \Omega} \sum v \cdot Qw\) the scalar product between the velocity field \(v\) and the orienting field \(w\) weighted by the orienting mask \(Q\).

cost(momentum_ini: Tensor) → Tensor
forward(z_0, n_iter=10, grad_coef=0.001, verbose=True, plot=False, sharp=None)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_all_arguments()
get_total_cost()
plot_cost(y_log=False)

To display the evolution of cost during the optimisation.

to_device(device)
class demeter.metamorphosis.constrained.ConstrainedMetamorphosis_integrator(residual_mask: Tensor | int | float, orienting_field: Tensor = None, orienting_mask: Tensor = None, sharp=False, **kwargs)

Bases: Geodesic_integrator

This class is an extension of the Geodesic_integrator class. It allows to integrate a geodesic with a constraint on the residual and the field using prior masks and fields.

priors one can add are: - a residual mask: \(M: \Omega \times t \rightarrow [0,1]\) a mask that for each time and pixel will control the amount of deformation versus the amount of photometric changes. - an orienting field: \(w: \Omega \times t \rightarrow \mathbb{R}^d\) a field that will guide the deformation - an orienting mask: \(Q: \Omega \times t \rightarrow [0,1]\) a mask that will control the prevalence of the orienting field over the deformation field. The geodesic equation is then given by:

\[\begin{split}\left\{ \begin{array}{rl} v_{t} &= - K_{V} (\sqrt{ M_{t} } p_{t} \nabla I_{t} + Q_{t} w_{t})\\ \dot{p_{t}} &= -\sqrt{ M_t } \nabla \cdot (p_{t}v_{t}) \\ z_{t} &= \sqrt{ 1 - M_t } p_{t} \\ \dot{I_{t}} &= - \sqrt{ M_t } v_{t} \cdot \nabla I_{t} + \sqrt{ 1-M_t } z_{t}. \end{array} \right.\end{split}\]
compute_field_sim()
plot_field_sim()
step()
step_deprecated()
to_device(device)
class demeter.metamorphosis.constrained.Reduce_field_Optim(source, target, geodesic, cost_cst, optimizer_method, mask_reduce, gamma)

Bases: Optimize_geodesicShooting

cost(residuals_ini: Tensor) → Tensor
forward(z_0, n_iter=10, grad_coef=0.001, verbose=True, sharp=None)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_total_cost()
plot_cost()

To display the evolution of cost during the optimisation.

to_device(device)

demeter.metamorphosis.data_cost module

This module contains the classes used to compute the data attachment term in the metamorphosis optimization. All data attachment terms must herit from the abstract class DataCost. The module contains the following classes: Ssd, Ssd_normalized, Cfm, SimiliSegs, Mutlimodal_ssd_cfm, Longitudinal_DataCost.

class demeter.metamorphosis.data_cost.Cfm(target, mask, **kwargs)

Bases: DataCost

This class is used to compute the data attachment term as a Cost Function Masking (CFM) term. It takes as a parameter the target image and the mask where the sum must be ignored.

Parameters:

  • target – torch.Tensor of shape [B,C,H,W] or [B,C,D,H,W], Target image

  • mask – torch.Tensor of the same shape as target

class demeter.metamorphosis.data_cost.DataCost(target, **kwargs)

Bases: ABC, Module

Abstract class for the data attachment term in the metamorphosis optimization. The class Optimize_geodesicShooting requires a data attachment term to be provided as a subclass of DataCost. All subclasses must implement the __init__ and __call__ methods that return the data attachment term.

This method is used to compute the data attachment term in the optimization process. It is meant to be given to a child of Optimize_geodesicShooting.

__init__(self, target, \*\*kwargs)

Initializes the class with the given target.

__repr__(self)

Returns a string representation of the DataCost object.

set_optimizer(self, optimizer)

Sets the optimizer object. Used during the initialization of the optimizer.

to_device(self, device)

Moves the target to the specified device.

__call__(self, at_step=-1, \*\*kwargs)

Abstract method that must be implemented by subclasses to return the data attachment term.

Parameters:

target – target image

set_optimizer(optimizer)

DataCost object are meant to be used along a method inherited from Optimize_geodesicShooting. This method is used to set the optimizer object and is usually used at the optimizer initialisation.

to_device(device)
class demeter.metamorphosis.data_cost.Longitudinal_DataCost(target_dict, data_cost: ~demeter.metamorphosis.data_cost.DataCost = <class 'demeter.metamorphosis.data_cost.Ssd'>, **kwargs)

Bases: DataCost

This class is used to compute the data
attachment term for longitudinal data. It takes

as a parameter an object inherited from `DataCost’ and apply the sum of the data attachment term over

the list of target images.

Parameters:

  • target_dict – List of dict of target images. Each dict must contain the key time with an integer value corresponding to the time of the data acquisition. The rest of the keys must by the one required by the provided data_cost object. (see example)

  • data_cost – DataCost object (default : Ssd)

Example

>>> from demeter.metamorphosis.data_cost import Cfm,Longitudinal_DataCost
>>> data_cost = Cfm
>>> target_dict = [
>>>         {'time':0,'target':torch.rand(1,1,100,100),'mask':torch.rand(1,1,100,100)},
>>>         {'time':6,'target':torch.rand(1,1,100,100),'mask':torch.rand(1,1,100,100)},
>>>         {'time':10,'target':torch.rand(1,1,100,100),'mask':torch.rand(1,1,100,100)}
>>>     ]
>>> ldc = Longitudinal_DataCost(target_dict,data_cost)
set_optimizer(optimizer)

DataCost object are meant to be used along a method inherited from Optimize_geodesicShooting. This method is used to set the optimizer object and is usually used at the optimizer initialisation.

to_device(device)
class demeter.metamorphosis.data_cost.Mutlimodal_ssd_cfm(target_ssd, target_cfm, source_cfm, mask_cfm, **kwargs)

Bases: DataCost

This class is used to compute the data attachment term as a combination of the Sum of Squared Differences (SSD) and the Cost Function Masking (CFM) terms on multimodal (or multichannel) images. It allows to compute the SSD on selected channels of the source image and the CFM on the remaining channels.

Parameters:

  • target_ssd – torch.Tensor of shape [B,C,H,W] or [B,C,D,H,W], Target image for the SSD term

  • target_cfm – torch.Tensor of the same shape as target_ssd, Target image for the CFM term

  • source_cfm – torch.Tensor of the same shape as target_ssd, Source image for the CFM term

  • mask_cfm – torch.Tensor of the same shape as target_ssd, Mask for the CFM term

set_optimizer(optimizer)

DataCost object are meant to be used along a method inherited from Optimize_geodesicShooting. This method is used to set the optimizer object and is usually used at the optimizer initialisation.

to_device(device)
class demeter.metamorphosis.data_cost.Mutual_Information(target, bins=20, min=0, max=1, mult=1.0)

Bases: DataCost

Mutual information measures the amount of information shared between two images. It is effective for multi-modal image registration.

\[I(X;Y) = \sum_{x \in X} \sum_{y \in Y} p(x,y) \log \left(\frac{p(x,y)}{p(x)p(y)}\right)\]

Where:

  • \(X\) and \(Y\) are the images being registered.

  • \(p(x,y)\) is the joint probability distribution of the intensities.

  • \(p(x)\) and \(p(y)\) are the marginal probability distributions of the intensities.

Parameters:

  • target (torch.Tensor) – Target image [B,C,H,W] or [B,C,D,H,W]

  • bins (int) – Number of bins for the histogram (default : 20)

  • min (float) – Minimum value for the histogram (default : 0)

  • max (float) – Maximum value for the histogram (default : 1)

  • mult (float) – Multiplicative factor for the mutual information (default : 1.0)

to_device(device)
class demeter.metamorphosis.data_cost.SimiliSegs(mask_source, mask_target, **kwargs)

Bases: DataCost

Rather than computing the SSD between the source and target images, this class computes the SSD between two given masks placed on the source and target masks respectively.

Parameters:

  • mask_source – torch.Tensor of shape [B,C,H,W] or [B,C,D,H,W], Source mask

  • mask_target – torch.Tensor of the same shape as mask_source, Target mask

set_optimizer(optimizer)

DataCost object are meant to be used along a method inherited from Optimize_geodesicShooting. This method is used to set the optimizer object and is usually used at the optimizer initialisation.

to_device(device)
class demeter.metamorphosis.data_cost.Ssd(target, **kwargs)

Bases: DataCost

This class is used to compute the data attachment term as a Sum of Squared Differences (SSD) term. It takes as a parameter the target image.

\[SSD(I,T) = \frac 12 \|I - T\|_2^2 = \frac 12\sum_{x\in \Omega} (I - T)^2\]

Parameters:

target – torch.Tensor of shape [B,C,H,W] or [B,C,D,H,W] Target image

Examples

target = torch.rand(1,1,100,100)
data_term = dt.Ssd(target)
mt.lddmm(source,target,geodesic,
    optimizer_method='adadelta',
    data_term = data_term
)
to_device(device)
class demeter.metamorphosis.data_cost.Ssd_normalized(target, **kwargs)

Bases: DataCost

This class is used to compute the data attachment term as a Sum of Squared Differences (SSD) term but normalized by the number of pixels. It takes as a parameter the target image.

\[SSD(I,T) = \frac 1{2 \#\Omega} \|I - T\|_2^2 = \frac 1{2 \#\Omega}\sum_{x\in \Omega} (I - T)^2\]
where \(\Omega\) is the set of pixels and \(\# \Omega\) is the number of pixels.

Parameters:

target – torch.Tensor of shape [B,C,H,W] or [B,C,D,H,W] Target image

to_device(device)

demeter.metamorphosis.joined module

This module contains the class for the joined mask metamorphosis. but it is broken for the moment. Please come back later.

class demeter.metamorphosis.joined.Weighted_joinedMask_Metamorphosis_Shooting(source, target, mask_source, mask_target, geodesic: Weighted_joinedMask_Metamorphosis_integrator, cost_cst: float, data_term=None, optimizer_method='LBFGS_torch', **kwargs)

Bases: Optimize_geodesicShooting

Perform the optimization of the weighted joined mask metamorphosis

Warning: self.source and self.target are a concatenation of the image and the mask ` source = torch.cat([source,mask_source],dim=1) `

cost(momentum_ini: Tensor) → Tensor
get_all_arguments()
get_ssd_def(only_image=False)
plot_cost()

To display the evolution of cost during the optimisation.

plot_imgCmp()

Display and compare the deformed image \(I_1\) with the target$

class demeter.metamorphosis.joined.Weighted_joinedMask_Metamorphosis_integrator(rho, **kwargs)

Bases: Geodesic_integrator

Dans cette version, on considère que l’image intégrée est une image à deux canaux, le premier étant l’image le second le masque. (i.e.: image.shape[1] == 2) avec image[:,0] l’image et image[:,1] le masque.

forward(image_mask, momentum_ini=0, **kwargs)

This method is doing the temporal loop using the good method _step_

Parameters:

  • image (tensor array of shape [1,1,H,W]) – Source image (\(I_0\))

  • momentum_ini (tensor array of shape [1,1,H,W]) – Momentum (\(p_0\)) or residual (\(z_0\))

  • save (bool, optional) – Option to save the integration intermediary steps, by default True it saves the image, field and momentum at each step in the attributes image_stock, field_stock and momentum_stock.

  • plot (int, optional) – Positive int lower than self.n_step to plot the indicated number of intermediary steps, by default 0

  • t_max (int, optional) – The integration will be made on [0,t_max], by default 1

  • verbose (bool, optional) – Option to print the progress of the integration, by default False

  • sharp (bool, optional) – Option to use the sharp integration, by default None

  • debug (bool, optional) – Option to print debug information, by default False

  • hamiltonian_integration (bool, optional) –

    Choose to integrate over first time step only or whole hamiltonian, in practice when True, the Regulation norms of the Hamiltonian are computed and saved in the good attributes (usually norm_v and norm_z),

    by default False

plot(n_figs=5)
step()
step_sharp()
to_device(device)

demeter.metamorphosis.load module

In this file you will find everything you need to load a previously saved optimisation.

demeter.metamorphosis.load.load_optimize_geodesicShooting(file_name, path=None, verbose=True)
load previously saved optimisation. Usually the file will be saved in the

OPTIM_SAVE_DIR witch is by default /saved_optim .

Parameters:

  • file_name (str) – name of the file to load

  • path (str, optional) – path to the file, by default OPTIM_SAVE_DIR = saved_optim

  • verbose (bool, optional) – print the loaded optimiser / integrator _repr_, by default True

Returns:

new_optim – the loaded optimiser

Return type:

Metamorphosis_Shooting

Examples

>>> import demeter.metamorphosis as mt
>>> # load the optimiser
>>> mr = mt.load_optimize_geodesicShooting('2D_23_01_2025_simpleToyExample_rho_0.00_000.pk1')

demeter.metamorphosis.simplex module

class demeter.metamorphosis.simplex.Simplex_sqrt_Metamorphosis_integrator(rho, **kwargs)

Bases: Geodesic_integrator

Class integrating over a geodesic shooting for images with values in the simplex.

..note::

In this class we integrate on the sphere using the square root function and reproject images on the simplex after. Thus, when accessing the image attribute, one should put it to the square to get the image in the simplex. >>> mp = Simplex_sqrt_Metamorphosis_integrator(rho=1, kernelOperator=kernelOperator, n_step=10) >>> mp.forward(image, momentum_ini,) >>> image_on_simplex = mp.image**2 >>> print( image_on_simplex.sum(dim=1) )

Parameters:

  • rho (float) – Control parameter for geodesic shooting intensities changes vs deformations. rho = 1 is LDDMM (pure deformation), rho = 0 is pure photometric changes. Any value in between is a mix of both.

  • kernelOperator (callable) – The reproducing kernel operator \(K\) that one must define to compute the field.

  • n_step (int) – Number of time step in the segment [0,1] over the geodesic integration.

  • dx_convention (str) – Convention for the pixel size. Default is ‘pixel’.

forward(image, momentum_ini, save=True, plot=0, t_max=1, verbose=False, sharp=None, debug=False, hamiltonian_integration=False)

This method is doing the temporal loop using the good method _step_

Parameters:

  • image (torch.Tensor of shape [1,C,H,W] or [1,C,D,H,W]) – Source image (\(I_0\)) C is the dimension of the simplex

  • momentum_ini (torch.Tensor of shape [1,C,H,W] or [1,C,D,H,W]) – Initial momentum (\(p_0\)) set by the user before the optimisation

  • save (bool, optional) – Option to save the integration intermediary steps, by default True it saves the image, field and momentum at each step in the attributes image_stock, field_stock and momentum_stock.

  • plot (int, optional) – Positive int lower than self.n_step to plot the indicated number of intermediary steps, by default 0

  • t_max (int, optional) – The integration will be made on [0,t_max], by default 1

  • verbose (bool, optional) – Option to print the progress of the integration, by default False

  • sharp (bool, optional) – Option to use the sharp integration, by default None

  • debug (bool, optional) – Option to print debug information, by default False

  • hamiltonian_integration (bool, optional) –

    Choose to integrate over first time step only or whole hamiltonian, in practice when True, the Regulation norms of the Hamiltonian are computed and saved in the good attributes (usually norm_v and norm_z),

    by default False

step()
class demeter.metamorphosis.simplex.Simplex_sqrt_Shooting(source, target, integrator, cost_cst, hamiltonian_integration=False, **kwargs)

Bases: Optimize_geodesicShooting

cost(momentum_ini: Tensor)
get_all_arguments()

demeter.metamorphosis.wraps module

demeter.metamorphosis.wraps.joined_metamorphosis(source_image, target_image, source_mask, target_mask, momentum_ini, rho, kernelOperator, data_term=None, dx_convention='pixel', n_step=10, n_iter=1000, grad_coef=2, cost_cst=0.001, optimizer_method='LBFGS_torch', plot=False, safe_mode=False, debug=False)
demeter.metamorphosis.wraps.simplex_metamorphosis(source, target, momentum_ini, kernelOperator, rho, data_term, dx_convention='pixel', n_step=10, n_iter=1000, grad_coef=2, cost_cst=0.001, plot=False, safe_mode=False, ham=False)

Module contents