Overview
A Julia package for fast 3D image quilting simulation.
This package implements an extension to the famous Efros-Freeman algorithm for texture synthesis and transfer in computer vision. Unlike the original algorithm developed for 2D images, our method can also handle 3D masked grids and pre-existing point-data very efficiently (the fastest in the literature). For more details, please refer to our paper in Citation.
Features
- Masked grids
- Hard data conditioning
- Soft data conditioning
- Fast computation with GPUs
Installation
Get the latest stable release with Julia's package manager:
Pkg.add("ImageQuilting")
For even faster computation with GPUs, please follow the instructions in GPU support.
Usage
This package is part of the GeoStats.jl framework. Solver options are displayed below:
ImageQuilting.ImgQuilt
— Type.ImgQuilt(var₁=>param₁, var₂=>param₂, ...)
Image quilting simulation solver as described in Hoffimann et al. 2017.
Parameters
Required
TI
- Training imagetilesize
- Tile size in x, y and z
Optional
overlap
- Overlap size in x, y and z (default to (1/6, 1/6, 1/6))cut
- Boundary cut algorithm (:boykov (default) or :dijkstra)path
- Simulation path (:raster (default), :dilation, or :random)inactive
- Vector of inactive voxels (i.e. tuples (i,j,k)) in the gridsoft
- A vector of(data,dataTI)
pairstol
- Initial relaxation tolerance in (0,1] (default to 0.1)
Global parameters
Optional
threads
- Number of threads in FFT (default to number of physical CPU cores)gpu
- Whether to use the GPU or the CPU (default to false)showprogress
- Whether to show or not the estimated time duration (default to false)
Low-level API
If you are interested in using the package without GeoStats.jl, please use the following function:
ImageQuilting.iqsim
— Function.iqsim(trainimg::AbstractArray{T,N}, tilesize::Dims{N},
simsize::Dims{N}=size(trainimg);
overlap::NTuple{N,Float64}=ntuple(i->1/6,N),
soft::AbstractVector=[], hard::HardData=HardData(), tol::Real=.1,
cut::Symbol=:boykov, path::Symbol=:raster, nreal::Integer=1,
threads::Integer=cpucores(), gpu::Bool=false,
debug::Bool=false, showprogress::Bool=false)
Performs image quilting simulation as described in Hoffimann et al. 2017.
Parameters
Required
trainimg
is any 3D array (add ghost dimension for 2D)tilesize
is the tile size (or pattern size)
Optional
simsize
is the size of the simulation grid (default to training image size)overlap
is the percentage of overlap (default to 1/6 of tile size)soft
is a vector of(data,dataTI)
pairs (default to none)hard
is an instance ofHardData
(default to none)tol
is the initial relaxation tolerance in (0,1] (default to .1)cut
is the cut algorithm (:dijkstra
or:boykov
)path
is the simulation path (:raster
,:dilation
or:random
)nreal
is the number of realizations (default to 1)threads
is the number of threads for the FFT (default to all CPU cores)gpu
informs whether to use the GPU or the CPU (default to false)debug
informs whether to export or not the boundary cuts and voxel reuseshowprogress
informs whether to show or not estimated time duration
The main output reals
consists of a list of 3D realizations that can be indexed with reals[1], reals[2], ..., reals[nreal]
. If debug=true
, additional output is generated:
reals, cuts, voxs = iqsim(..., debug=true)
cuts[i]
is the boundary cut for reals[i]
and voxs[i]
is the associated voxel reuse.
The major difference compared to the high-level API is that the iqsim
function has no notion of coordinate system, and you will have to pre-process the data manually to match it with the cells in the simulation grid.
GeoStats.jl takes the coordinate system into account and also enables parallel simulation on HPC clusters.