Home

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

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 image
  • tilesize - 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 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)

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 of HardData (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 reuse
  • showprogress 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.