Overview

A Julia package for fast 3D image quilting simulation.

Build Status Coverage Status Stable Documentation Latest Documentation

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.

3D Quilting Animation

Features

  • Masked grids
  • Hard data conditioning
  • Soft data conditioning
  • Fast computation with GPUs

Installation

Get the latest stable release with Julia's package manager:

] add ImageQuilting

For even faster computation with GPUs, please follow the instructions in GPU support.

Talks

Below is a list of talks related to this project. For more material, please subscribe to the YouTube channel.

Usage

This package is part of the GeoStats.jl framework. Solver options are displayed below:

ImageQuilting.IQType
IQ(var₁=>param₁, var₂=>param₂, ...)

Image quilting simulation solver as described in Hoffimann et al. 2017.

Parameters

Required

  • trainimg - Training image from which to extract tiles
  • tilesize - Tuple with tile size for each dimension

Optional

  • overlap - Overlap size (default to (1/6, 1/6, ..., 1/6))
  • path - Simulation path (:raster (default), :dilation, or :random)
  • mapping - Data mapping method (default to NearestMapping())
  • inactive - Vector of inactive voxels (i.e. CartesianIndex) in the grid
  • soft - A vector of (data,dataTI) pairs
  • tol - 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)

References

  • Hoffimann et al 2017. Stochastic simulation by image quilting of process-based geological models.
  • Hoffimann et al 2015. Geostatistical modeling of evolving landscapes by means of image quilting.

Low-level API

If you are interested in using the package without GeoStats.jl, please use the following function:

ImageQuilting.iqsimFunction
iqsim(trainimg::AbstractArray{T,N}, tilesize::Dims{N},
      simsize::Dims{N}=size(trainimg);
      overlap::NTuple{N,<:Real}=ntuple(i->1/6,N),
      soft::AbstractVector=[], hard::Dict=Dict(), tol::Real=.1,
      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 Julia array
  • tilesize is the tile 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 a dictionary mapping coordinates to data values (default to none)
  • tol is the initial relaxation tolerance in (0,1] (default to .1)
  • 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 reuse
  • showprogress informs whether to show or not estimated time duration

The main output reals consists of a list of 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.

source

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.