Skip to content

ImageQuilting

Image quilting: realizations pasted together from patches of a training image (Efros and Freeman, 2001; Mariethoz and Lefebvre, 2014).

Overlapping patches cover the targets along a raster path, x fastest, then y, then z. Each patch is drawn at random among the n_best positions of the training image that best match what the targets already hold under it: the cells of earlier patches, and the hard data weighted by data_weight. It joins the earlier patches along the seam where the two differ least: a minimum-error boundary cut in 2D, a graph cut in 3D (Kwatra et al., 2003). Positions whose patch holds a null of the training image are never pasted. Hard data steer the choice and are never pasted over.

The mismatch of a cell is 0 or 1 for codes, and the squared difference over the squared value range of the training image for values.

Two more kinds of data steer the choice when simulate is given them. Soft probabilities of each code at the targets add soft_weight times the mean of 1 - P(c) over the patch, c the code the patch puts in a block. A secondary variable known over both the training image and the targets, such as seismic amplitude, adds secondary_weight times the mean squared difference between the two over the patch, over the squared range of the training image's secondary column. A patch that compares many cells has its costs computed by FFT, with the same realizations.

Parameters:

Name Type Description Default
ti BlockModel

Regular or masked training image. Patterns are read in cell index space, so its origin, cell size and rotation play no part.

 required
column str

The float column of ti to copy.

 required
patch_size int or sequence of int

Cells of a patch along x, y and z (one int for all), clamped to the training image and to the targets.

 40
overlap int or sequence of int

Cells a patch shares with the one before it along each axis, at most half the patch; by default a sixth of the patch, at least 1.

 required
n_best int

How many of the cheapest positions a patch is drawn from.

 10
data_weight float

Weight of the hard data against the overlap in the choice of a patch; 0 leaves them out of it.

 5.0
categorical bool

Whether the column holds codes (categories 0 to 254) or continuous values. By default it is categorical when every value is an integer from 0 to 254; set False for integer-valued continuous variables.

 required
secondary str

The float column of ti holding the secondary variable; simulate then needs it at the targets.

 required
secondary_weight float

Weight of the secondary variable against the overlap.

 1.0
soft_weight float

Weight of the soft probabilities against the overlap.

 1.0

Examples:

>>> grid = bt.BlockModel((0, 0, 0), (1, 1, 1), (100, 100, 1))
>>> ti = bt.object_training_image(
...     grid, [{"shape": "channel", "code": 1, "proportion": 0.3, "width": 6}], seed=1
... )
>>> targets = bt.BlockModel((0, 0, 0), (1, 1, 1), (80, 80, 1))
>>> summary = bt.ImageQuilting(ti, "facies", patch_size=20).simulate(targets, n=10)

categorical property 

categorical

Whether the training image holds codes rather than continuous values.

fit method descriptor 

fit(coords, values)

Takes hard data, which every realization reproduces. A datum outside the targets is ignored; of several in one target block the first is kept.

Parameters:

Name Type Description Default
coords (array_like, shape(n, 2) or (n, 3), PointSet or BlockModel)
required
values array_like, shape (n,), or str

Codes of the training image, or values, or the column of coords holding them.

 required

Returns:

Type Description
ImageQuilting

This simulator.

from_parquet staticmethod 

from_parquet(path)

Reads to_parquet output; raises InvalidInput on another class's file or a newer format.

simulate method descriptor 

simulate(
    targets,
    *,
    n=100,
    seed=0,
    keep=None,
    soft=None,
    secondary=None,
)

Summary of n realizations, each seeded from seed and its index.

Parameters:

Name Type Description Default
targets BlockModel

Regular or masked grid; every block is simulated.

 required
n int
100
seed int
0
keep bool or sequence of int

Return all realizations, or these 0-based ones, beside the summary.

 None
soft sequence of str or array_like, shape (targets, k)

Probability of each code 0..k at every target block, as k columns of targets in code order or an array; a row of nulls carries none. Rows are scaled to sum to 1. Categorical training images only.

 None
secondary (str or array_like, shape(targets))

The secondary variable at the targets, as a column of targets or an array; null where unknown. Needed exactly when the simulator was built with secondary.

 None

Returns:

Type Description
CategoricalSummary or SimulationSummary

Categorical for a categorical training image, else continuous.

to_parquet method descriptor 

to_parquet(path)

Writes the training image as a Parquet column, and parameters and hard data as JSON in the file metadata; from_parquet reads it back.

used in