| | |
- builtins.dict(builtins.object)
-
- ImplicitConstraintDict
- builtins.object
-
- Constraint
- ConstraintFilter
- ConstraintSet
- enum.Enum(builtins.object)
-
- ConstraintType
class Constraint(builtins.object) |
| |
Constraint(composite, index1=None, index2=None, dx=None, dy=None, score=None, error=None, type=<ConstraintType.NORMAL: 'normal'>)
A class to represent the pixel offset between two images in a composite.
The Constraint is an important component of the ConStitch algorithm, and converting
from global positions of images to a set of constraints between images and back
is the main algorithm used to stitch image sets.
It is not normally necessary to instantiate Constraint objects directly, instead
they are created from the existing image positions with CompositeImage.constraints
or by calculating new constraints with the Constraint.calculate or ConstraintSet.calculate
functions.
The class ConstraintSet is used as a container to manipulate and filter large collections
of constraints
Fields:
composite (Composite): A reference to the composite that holds the images of this constraint
index1 (int): The index in the composite to the first image.
This index will always be less than index2, if index1 > index2 then
the constraint should have been created swapping index1 and index2
index2 (int): The index in the composite to the second image
dx (int): X coordinate offset from image1 to image2
This offset is measured from the pixel at 0,0 of image1
to the pixel at 0,0 of image2, or put another way the
offset is measured from the position of the box of the first image
to the position of the box of the second image
dy (int): Y coordinate offset from image1 to image2
Measured the same way as dx, from the 0,0 pixel in image1
to the 0,0 pixel in image2, or from box1.position to box2.position
score (float): A value that relatively scores how well the alignment is
This score is generated by the alignment algorithm, to allow for filtering
and weighting of constraints based on it. Constraints calculated
from existing image positions will have a score of None
error (int): The uncertanty of the specified alignment
This error value is treated as an uncertanty, saying the true alignment
is equal to (dx ± error, dy ± error). This is typically zero
unless the images were downscaled, and the uncertanty of original
image positions can be specified by the user. When calculating new constraints
only offsets that fall within these bounds are considered, see section1 and section2
for more information on how
|
| |
Methods defined here:
- __init__(self, composite, index1=None, index2=None, dx=None, dy=None, score=None, error=None, type=<ConstraintType.NORMAL: 'normal'>)
- Initialize self. See help(type(self)) for accurate signature.
- __repr__(self)
- Return repr(self).
- __str__(self)
- Return str(self).
- calculate(self, aligner=None, executor=None)
- Calculates a new constraint using the specified alignment algorithm.
More information on how alignment is performed can be found at constitch.alignment
- new(self, dx=None, dy=None, score=None, error=None, type=None)
- Creates a new constraint between the images of this one. Normally used
by alignment algorithms when they calculate a
new constraint
Params:
dx, dy, score, error, type: See docs for Constraint.__init__()
- new_rescaled(self, dx=None, dy=None, score=None, error=None, type=None)
- Creates a new constraint, similar to Constraint.new. This method is used when
the new constraint was calculated using Constraint.resized_image1 and Constraint.resized_image2,
normally when aligning in an Aligner. This means that dx and dy are expected to be
the offsets in these resized images, and they are converted into an offset in the original image,
taking into account the amount each image has been resized. The error is also adjusted, eg
if the alignment in the rescaled images is accurate to 8 pixels but the images were upscaled by
4 pixels, the true error would be 2
- new_section(self, dx=None, dy=None, score=None, error=None, type=None)
- Creates a new constraint, similar to Constraint.new. This method is used when
the new constraint was calculated using Constraint.section1 and Constraint.section2,
normally when aligning in an Aligner. This means that dx, dy, and error are expected to be
relative to the coordinate space of the sections, and are converted into an offset and error for the whole image,
taking into account the bounds of the sections and the amount each image has been
resized
- to_obj(self)
Readonly properties defined here:
- box1
- Retrieves the box of image1 from the composite,
equivalent to self.composite.boxes[self.index1]
- box2
- Retrieves the box of image2 from the composite,
equivalent to self.composite.boxes[self.index2]
- difference
- The difference between the offset specified in this constraint and the
difference in positions of the images currently, from self.box1 and self.box2.
If this constraint was calculated using an alignment algorithm this is the
correction the alignment algorithm applied, and if this is after the global
positions of the images have been solved then this is the error present when
solving for the positions
- image1
- Retrieves the image1 from the composite,
equivalent to self.composite.images[self.index1]
- image2
- Retrieves the image2 from the composite,
equivalent to self.composite.images[self.index2]
- implicit
- Whether or not this constraint is implicit, meaning it was calculated
from existing image positions and was not calculated using an alignment
algorithm
- length
- The length of the offset between images, sqrt(dx^2 + dy^2)
- modeled
- overlap
- The overlap of the two images, in total number of pixels. If the images
don't overlap, it will be negative
- overlap_ratio
- The overlap of the two images, as a ratio of the number of pixels overlapping
over the maximum possible number of pixels overlapping
- overlap_ratio_x
- The overlap of the two images across the x axis, as a ratio of the image size.
If the images are different sizes it is a ratio with the smaller images size.
- overlap_ratio_y
- The overlap of the two images across the y axis, as a ratio of the image size.
If the images are different sizes it is a ratio with the smaller images size.
- overlap_x
- The overlap of the two images across the x axis, in pixels
- overlap_y
- The overlap of the two images across the y axis, in pixels
- pair
- The two indices of the images in the composite as a tuple
- pixel_scale_ratio
- The difference in pixel scale between image1 and image2. For example
if image2 was taken with 2x the magnification and thus each pixel is
half the size of each pixel in image1, the scale ratio would be 2 / 1
as image2 would need to be scaled up by 2 to have the same pixel size.
The ratio is returned as a fractions.Fraction for the x and y axes.
- resized_image1
- Retrieves the first image of the constraint, resizing it so that
the scale of pixels between image1 and image2 is the same.
This may require computing the resized image, but it will be cached
in the composite and any subsequent calls will not require any calculation
- resized_image2
- Retrieves the first image of the constraint, resizing it so that
the scale of pixels between image1 and image2 is the same.
This may require computing the resized image, but it will be cached
in the composite and any subsequent calls will not require any calculation
- section1
- Returns the section of image1 relevant for alignment, that is the
section of image1 that overlaps with image2, expanded to include self.error,
and resized so that both sections have the same pixel scale.
If error is infinite or None this will be the same as self.resized_image1.
Usually used by the alignment algorithm when calculating new constraints,
see the docs for Aligner for more info
- section1_bounds
- section2
- Returns the section of image2 relevant for alignment, that is the
section of image2 that overlaps with image1, expanded to include self.error,
and resized so that both sections have the same pixel scale.
If error is infinite or None this will be the same as self.resized_image1.
- section2_bounds
- touching
- True if the images are either overlapping (self.overlap > 0) or touching
along the x or y axis (self.overlap_x > 0 or self.overlap_y > 0)
Data descriptors defined here:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class ConstraintFilter(builtins.object) |
| |
ConstraintFilter(obj=None, **kwargs)
A class that represents a filter on constraints. Can be a threshold
on a attribute of constraints, eg ConstraintFilter(min_score=0.5),
a required value or constraint type, eg ConstraintFilter(touching=True, implicit=True),
or a custom function that returns a bool, eg ConstraintFilter(lambda const: const.box1.position[0] < 5000)
Filters can be created and combined with & or | and passed to ConstraintSet.filter() to select for
specific constraints.
|
| |
Methods defined here:
- __and__(self, other)
- Combines two filters, creating a new filter that evaluates
to True when both others evaluate to True
- __call__(self, constraint)
- Evaluates the filter on a constraint.
Returns whether or not the constraint should be kept.
- __init__(self, obj=None, **kwargs)
- A filter can be constructed in multiple ways:
ConstraintFilter(params)
ConstraintFilter(**kwargs)
Constructing with a dictionary of parameters. Each entry in the
dictionary or keyword parameter must be an attribute of a Constraint
instance, optionally prepended with min_ or max_.
When filtering, the specified attribute will be retrieved from each constraint
and compared to the value passed here. If prepended with min_ values greater or equal
will be kept and if prepended with max_ values less than or equal will be kept,
otherwise only values that are equal are kept.
For example, the filter ConstraintFilter(min_score=0.5) will keep constrains where
constraint.score >= 0.5 is True.
When multiple parameters are specified, only constraints that match all parameters
will be kept. If you want to match either parameter, create multiple filters and combine
them, eg ConstraintFilter(touching=True) | ConstraintFilter(min_score=0.5)
ConstraintFilter(func)
Constructing from a function. The passed function is evaluated for each constraint,
if True the constraint is kept. This has the same behaviour as the builtin filter()
- __or__(self, other)
- Combines two filters, creating a new filter that evaluates
to True when either other filters evaluate to True
- __str__(self)
- Return str(self).
- alwaystrue(self)
- fromdict(self, params)
Data descriptors defined here:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
|
class ConstraintSet(builtins.object) |
| |
ConstraintSet(constraints=None)
A class that stores a set of constraints
Many important algorithms when stitching revolve around manipulating
sets of constraints, thus we have the class ConstraintSet to represent
collections of Constraints and filter/manipulate them. A ConstraintSet
behaves mostly like a dictionary mapping pairs of images to Constraints.
ConstraintSets are normally created from CompositeImage.constraints
or ConstraintSet.calculate, but they can be instantiated with any
sequence of Constraints
|
| |
Methods defined here:
- __contains__(self, obj)
- Tests if a Constraint or a pair is contained
- __getattr__(self, name)
- Some attributes of Constraint can be accessed from a ConstraintSet, returned as a numpy
array of the values for all constraints, in the order of self.keys()
- __getitem__(self, pair)
- __init__(self, constraints=None)
- Initialize self. See help(type(self)) for accurate signature.
- __iter__(self)
- Iterates through all constraints in this set
- __len__(self)
- add(self, other)
- Add constraints to this set
If a constraint between the same images is already present, the constraint
with the lower error is kept and the other is removed.
In the case of equal errors the new constraint is kept
Args:
other (Constraint or sequence of Constraints): Constraint or Constraints to add
Raises:
ValueError: The constraint(s) to be added are from a different CompositeImage
- calculate(self, aligner=None, executor=None)
- Calculates new constraints using an alignment algorithm
For every constraint the provided aligner is invoked to calculate
a new constraint. See constitch.alignment for more information on
alignment.
Args:
aligner (constitch.Aligner): default self.composite.aligner
The aligner that is used to calculate the new constraints
executor (concurrent.futures.Executor): default self.composite.executor
A thread or process pool instance to parallelize the computation,
as some aligners can be quite slow
- debug(self, *args, **kwargs)
- A shorthand for self.composite.debug
- filter(self, obj=None, limit=None, random=False, sorted_by=None, **kwargs)
- Returns a new ConstraintSet with only constraints that are
matching the specified filter.
Either a ConstraintFilter instance can be passed in or an object that
can be converted into a filter, ie a dictionary or a set of keyword arguments.
See ConstraintFilter for the full documentation on creating a filter.
Args:
obj: The filter or object to be converted into a filter. Can be many types:
If it is a ConstraintFilter or a callable it is applied as the filter
If it is a numpy bool array, it is used to filter constraint, mapping with
the order of self.constraints
If it is a set or list of pairs of indices, only constraints for those pairs are kept
limit (int): The maximum number of constraints returned
random (bool): If true the constraints are shuffled
Normally used in conjunction with the limit argument to select a random
sample of the constraints
sorted_by (function or str): key to sort constraints on
Either a function that can be passed as a key to sorted() or a string
that is an attribute of a constraint. Used to sort the constraints, normally
used with the limit argument
kwargs: Any keyword arguments are passed to a new ConstraintFilter() constructor
and applied as a filter
Returns:
A new ConstraintSet with the filtered Constraints
- find(self, obj=None, **kwargs)
- Returns the first constraint to match a filter
Uses the same interface as self.filter but returns the first
constraint that matches the filter
- fit_model(self, model=None, outliers=False, random_state=12345)
- Fits a linear model to the constraints in this set
This learns the motion of the microscope stage, which can be used to fill in
constraints in areas where there are not enough features to align.
The model is trained on the relation between the offset in image positions,
that is box2.position - bos1.position, and the offset specified in dx and dy.
Args:
model (sklearn base model): default constitch.SimpleOffsetModel()
The linear model to train, it should be a sklearn model class, meaning
it has a fit and predict method. The fit method is called
with X as a 4 column matrix containing the x and y positions of image1 and image2
for all constraints, and y as a 2 column matrix with dx and dy for all constraints
outliers (bool): Whether to use an outlier resistant model
If set to True the provided model is wrapped in sklearn.linear_model.RANSACRegressor,
and the inlier and outlier classifications are added onto the returned
result as result.inliers and result.outliers. These are new ConstraintSets
containing only the inliers and outliers that the model classified
random_state: the random state passed to RANSACRegressor when outliers=True
Returns:
An Aligner class that can be used to calculate new constraints, using
the linear model fit here.
- items(self)
- keys(self)
- merge(self, other, *others)
- Returns a new ConstaintSet with combined constraints from this and other sets
As with add(), if constraints between the same image pair are present in both sets
then the constraint with the lowest error is kept, with ties defaulting to constraints in the
last passed in set
Args:
other (Constraint or sequence of Constraints): Constraint or Constraints to
merge with new set
Raises:
ValueError: The constraints to be merged are from a different ConstraintImage
- neighborhood_difference(self, constraint)
- A metric that measures how well this constraint matches the image
positions, taking into account neighboring constraints.
- neighboring(self, constraint, depth=1)
- Returns a new ConstraintSet containing only constraints that
are connected to an initial constraint or image
The starting location is specified by passing either a constraint, a
image index, or a sequence of either. Constraints are added by BFS to
the requested depth. Any constraints provided as a starting location
are not included in the resulting set
- progress(self, iter, **kwargs)
- A shorthand for self.composite.progress
- remove(self, other)
- Remove constraints from this set
Args:
other (Constraint, (int, int) or sequence of either):
The constraints or pairs to be removed
Raises:
KeyError: The specified constraint does not exist
- solve(self, solver='mae', **kwargs)
- Solve the constraints to get a global position for each image
Args:
solver (constitch.Solver or str): default constitch.LinearSolver()
The solver method that is used to combine the overconstrainted
system of constraints and optimize for the best global positions.
Options include 'mse' for standard least squares solving, 'mae'
for solving while minimizing mean absolute error, 'huber' for
minimizing the huber loss, or any subclass of constitch.Solver.
More info can be found in constitch.solving
**kwargs: Arguments passed to the constructor of the solver.
Any arguments specified here are passed to the constructor
of the solver, for example if solver='huber' epsilon=5 could
be included to change the default epsilon parameter for huber loss.
Cannot be specified if solver is an already instantiated constitch.Solver
instance.
Returns:
The solver instance, with an attribute positions containing a dict
mapping image indices to their global positions
- values(self)
Readonly properties defined here:
- composite
- The composite that contains all the images of the constraints of this
set. If constraints from a different constraint are added, an error will be
raised. If this instance contains no constraints this will return None
Data descriptors defined here:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
Data and other attributes defined here:
- ATTRS = ['dx', 'dy', 'score', 'error', 'overlap', 'overlap_x', 'overlap_y', 'overlap_ratio', 'overlap_ratio_x', 'overlap_ratio_y', 'size', 'difference']
|
class ConstraintType(enum.Enum) |
| |
ConstraintType(value, names=None, *, module=None, qualname=None, type=None, start=1)
An enumeration.
|
| |
- Method resolution order:
- ConstraintType
- enum.Enum
- builtins.object
Data and other attributes defined here:
- IMPLICIT = <ConstraintType.IMPLICIT: 'implicit'>
- MODELED = <ConstraintType.MODELED: 'modeled'>
- NORMAL = <ConstraintType.NORMAL: 'normal'>
Data descriptors inherited from enum.Enum:
- name
- The name of the Enum member.
- value
- The value of the Enum member.
Readonly properties inherited from enum.EnumMeta:
- __members__
- Returns a mapping of member name->value.
This mapping lists all enum members, including aliases. Note that this
is a read-only view of the internal mapping.
|
class ImplicitConstraintDict(builtins.dict) |
| |
ImplicitConstraintDict(composite, pairs_func)
|
| |
- Method resolution order:
- ImplicitConstraintDict
- builtins.dict
- builtins.object
Methods defined here:
- __getitem__(self, pair)
- x.__getitem__(y) <==> x[y]
- __init__(self, composite, pairs_func)
- Initialize self. See help(type(self)) for accurate signature.
- items(self)
- D.items() -> a set-like object providing a view on D's items
- keys(self)
- D.keys() -> a set-like object providing a view on D's keys
- values(self)
- D.values() -> an object providing a view on D's values
Data descriptors defined here:
- __dict__
- dictionary for instance variables (if defined)
- __weakref__
- list of weak references to the object (if defined)
Methods inherited from builtins.dict:
- __contains__(self, key, /)
- True if the dictionary has the specified key, else False.
- __delitem__(self, key, /)
- Delete self[key].
- __eq__(self, value, /)
- Return self==value.
- __ge__(self, value, /)
- Return self>=value.
- __getattribute__(self, name, /)
- Return getattr(self, name).
- __gt__(self, value, /)
- Return self>value.
- __ior__(self, value, /)
- Return self|=value.
- __iter__(self, /)
- Implement iter(self).
- __le__(self, value, /)
- Return self<=value.
- __len__(self, /)
- Return len(self).
- __lt__(self, value, /)
- Return self<value.
- __ne__(self, value, /)
- Return self!=value.
- __or__(self, value, /)
- Return self|value.
- __repr__(self, /)
- Return repr(self).
- __reversed__(self, /)
- Return a reverse iterator over the dict keys.
- __ror__(self, value, /)
- Return value|self.
- __setitem__(self, key, value, /)
- Set self[key] to value.
- __sizeof__(...)
- D.__sizeof__() -> size of D in memory, in bytes
- clear(...)
- D.clear() -> None. Remove all items from D.
- copy(...)
- D.copy() -> a shallow copy of D
- get(self, key, default=None, /)
- Return the value for key if key is in the dictionary, else default.
- pop(...)
- D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
If the key is not found, return the default if given; otherwise,
raise a KeyError.
- popitem(self, /)
- Remove and return a (key, value) pair as a 2-tuple.
Pairs are returned in LIFO (last-in, first-out) order.
Raises KeyError if the dict is empty.
- setdefault(self, key, default=None, /)
- Insert key with a value of default if key is not in the dictionary.
Return the value for key if key is in the dictionary, else default.
- update(...)
- D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
In either case, this is followed by: for k in F: D[k] = F[k]
Class methods inherited from builtins.dict:
- __class_getitem__(...) from builtins.type
- See PEP 585
- fromkeys(iterable, value=None, /) from builtins.type
- Create a new dictionary with keys from iterable and values set to value.
Static methods inherited from builtins.dict:
- __new__(*args, **kwargs) from builtins.type
- Create and return a new object. See help(type) for accurate signature.
Data and other attributes inherited from builtins.dict:
- __hash__ = None
| |