gorph

README

Table of Contents

1. About
2. Dependencies
3. License
4. Installation
5. Usage/API
6. Contributing
7. Authors

About ---

Gorph is a library that manipulates graphic images in order to procedurally modify or create derived images.

It is currently under development with the goal of enabling server-side clients to pre-render or procedurally generate images.

The name is an homage to the library itself. It is derived from using the "morph" of two images to create a keyframe-based animation system. It also comes from "gopher" or "golang". Morphing the two different words gives the perhaps-not-quite-as-humorous result.

This library is still unstable, please do not hesitate to contact me with questions. Comments in the source are nonexistant, and is the first item to be remedied.

License ---

Gorph is released under the MIT Expat License, a permissive free software license. Contributing back to the source is appreciated greatly, but not demanded by the license. A copy of the license is distributed with the source code.

Dependencies ---

At this time, no additional dependencies are required beyond the golang standard library.

Installation ---

If Go is not installed, please do so first.

To download the source, use the command:

go get github.com/cjslep/gorph

Then, to build the source:

go build github.com/cjslep/gorph

To ensure all tests pass, run:

go test github.com/cjslep/gorph

Note that the dev-unstable branch may not pass all tests.

Usage / API ---

This section will be more detailed once development stabilizes. The following functions are targeted:

• Resize - Adjusts an image to new bounds. The aspect ratio may change. Anti-aliasing needed except in cases where pixels line up nicely.
• Scale - Adjusts an image by a percent, preserving aspect ratio. Anti-aliasing needed except in cases where pixels line up nicely.
• CrossDissolve - Applies a weight on a pixel-by-pixel basis between images to produce a faded new image.
• Morph - Keyframe image interpolation based on a grid.
• MorphFeature - Keyframe image interpolation based on a feature line.

Additionally, internally there are helpful functions that are currently buried that need to be extracted, or need to be written:

• bicubicInterpolation - Interpolates a pixel color from an image using bicubic interpolation.
• bilinearInterpolation - Interpolates a pixel color from an image using bilinear interpolation, where color changes may not be continuous over square boundaries.
• nearestNeighborInterpolation - Interpolates a pixel color from an image using the closest neighboring pixel.
• mergePixelsInLine - Already written, could be broken out into simpler pieces.

Contributing ---

The license governing this source code does not require users to contribute back to this source code, nor does it prevent users from creating proprietary derivative works. However, contributions back to the source are greatly appreciated.

Comments in the source are nonexistant, and is the first item to be remedied.

Authors ---

In no particular order:

• cjslep

Documentation

Overview

Package gorph manipulates graphic images in order to procedurally modify or create derived images. The datastructures and algorithms provided allow client codes to pre-render or procedurally generate new images from base images.

This library is designed to use the standard libraries as much as possible in order to leverage the "image" and "image/color" libraries heavily.

Index

• func CrossDissolve(dissolving []image.Image, weights []float64) (image.Image, error)
• func Distance(p1, p2 Float64Point) float64
• func DistanceImagePoint(p1, p2 image.Point) float64
• func MaxInt(x, y int) int
• func Morph(numMorphs int, start, dest image.Image, mGrid MorphGrid, ...) ([]image.Image, error)
• type Float64Point
  • func CubicCatmullRomInterpolation(points []Float64Point, alpha float64, totSteps int) ([]Float64Point, error)
  • func CubicCatmullRomInterpolationImagePoints(points []image.Point, alpha float64, totSteps int) ([]Float64Point, error)
  • func LinearInterpolation(start, end Float64Point, fractionFromStart float64) Float64Point
  • func LinearInterpolationImagePoints(start, end image.Point, fractionFromStart float64) Float64Point
  • func ToFloat64Point(pt image.Point) Float64Point
• type InterpolationFunc
• type MorphGrid
  • func NewMorphGrid() *MorphGrid
  • func (m *MorphGrid) AddPoints(horizLine, vertLine int, startPt, destPt image.Point)
  • func (m *MorphGrid) HorizontalGridlineCount() int
  • func (m *MorphGrid) HorizontalLine(index int) (source, dest []image.Point)
  • func (m *MorphGrid) Points(horizLine, vertLine int) (image.Point, image.Point, error)
  • func (m *MorphGrid) RemovePoints(horizLine, vertLine int) error
  • func (m *MorphGrid) VerticalGridlineCount() int
  • func (m *MorphGrid) VerticalLine(index int) (source, dest []image.Point)

Functions

func CrossDissolve

func CrossDissolve(dissolving []image.Image, weights []float64) (image.Image, error)

CrossDissolve weights a series of images on a pixel-by-pixel basis in order to produce a resulting image. Returns an error if any of the image bounds do not match, if one or no images are provided, or the number of images do not match the number of weights.

func Distance

func Distance(p1, p2 Float64Point) float64

Distance computes the distance between two floating-point points.

func DistanceImagePoint

func DistanceImagePoint(p1, p2 image.Point) float64

DistanceImagePoint computes the distance between two integer points.

func MaxInt

func MaxInt(x, y int) int

MaxInt is a convenience function that returns the larger of two integers.

func Morph

func Morph(numMorphs int, start, dest image.Image, mGrid MorphGrid, timeInterp InterpolationFunc, nominalTimeConversion func(float64) float64) ([]image.Image, error)

Morph performes a keyframe-based morphing of two images in order to interpolate a new set of transition images. It is based on the coordinate grid approach to morphing an image, as opposed to a feature line. numMorphs - the number of morph images to create start - starting image dest - ending image mGrid - a MorphGrid representing homogulous points on both images timeInterp - function to use to interpolate cross-fading grids over time nominalTimeConversion - function to covert actual time frame of grid to nominal time used in cross fading. The parameter and returned value must lie in the range [0.0, 1.0]

Types

type Float64Point

type Float64Point struct {
	X float64
	Y float64
}

Float64Point represents a double precision point. It is capable of representing fractional pixels in the same intention as an image.Point. A floating point of (1.25, 2.5) represents the location a quarter of the way horizontally into and halfway down the pixel given by image.Point(1, 2).

func CubicCatmullRomInterpolation

func CubicCatmullRomInterpolation(points []Float64Point, alpha float64, totSteps int) ([]Float64Point, error)

CubicCatmullRomInterpolation computes the Catmull-Rom spline from a given set of points. There must be at least three points passed in, the alpha value must be in the range of [0.0, 1.0] and the total steps must be 2 or greater. If two points are passed in, linear interpolation occurs instead. The alpha parameter dictates the kind of Catmull-Rom spline generated; a value of 0 yields a Uniform curve, a value of 0.5 yields a Centripetal curve (which will not form loops), and a value of 1.0 creates a Chordal curve.

func CubicCatmullRomInterpolationImagePoints

func CubicCatmullRomInterpolationImagePoints(points []image.Point, alpha float64, totSteps int) ([]Float64Point, error)

CubicCatmullRomInterpolationImagePoints computes the Catmull-Rom spline from a given set of image points. There must be at least three points passed in, the alpha value must be in the range of [0.0, 1.0] and the total steps must be 2 or greater. The alpha parameter dictates the kind of Catmull-Rom spline generated; a value of 0 yields a Uniform curve, a value of 0.5 yields a Centripetal curve (which will not form loops), and a value of 1.0 creates a Chordal curve.

func LinearInterpolation

func LinearInterpolation(start, end Float64Point, fractionFromStart float64) Float64Point

LinearInterpolation linearly interpolates the Float64Point between two Float64Points based on the ratio of the distance from the start point over the total distance.

func LinearInterpolationImagePoints

func LinearInterpolationImagePoints(start, end image.Point, fractionFromStart float64) Float64Point

LinearInterpolationImagePoints linearly interpolates the Float64Point between two image points based on the ratio of the distance from the start point over the total distance.

func ToFloat64Point

func ToFloat64Point(pt image.Point) Float64Point

ToFloat64Point

type InterpolationFunc

type InterpolationFunc func(start, end image.Point, fractionFromStart float64) Float64Point

InterpolationFunc interpolates a Float64Point between two image points based on a ratio distance from the starting point to the ending point, such that fractionFromStart lies on the interval [0.0, 1.0]. The value 0.0 maps to the starting point, and 1.0 to the end point.

type MorphGrid

type MorphGrid struct {
	// contains filtered or unexported fields
}

MorphGrid is a metadata structure usually used alongside images for specifying parameters used in transformations. The MorphGrid consists of two grids in order to hold data for a pre-morph and post-morph state. It manages these pairs of points so accompanying morphing algorithms can easily use the parametric information between homogulous lines. For details on how a MorphGrid is exactly used, please refer to a morphing algorithm's documentation.

func NewMorphGrid

func NewMorphGrid() *MorphGrid

NewMorphGrid supplies a new instance of a MorphGrid.

func (*MorphGrid) AddPoints

func (m *MorphGrid) AddPoints(horizLine, vertLine int, startPt, destPt image.Point)

AddPoints adds two homogulous points for a before and after image on the specified horizontal and vertical line indices. Replaces any preexisting points.

func (*MorphGrid) HorizontalGridlineCount

func (m *MorphGrid) HorizontalGridlineCount() int

HorizontalGridlineCount determines the number of horizontal grid lines that have been specified.

func (*MorphGrid) HorizontalLine

func (m *MorphGrid) HorizontalLine(index int) (source, dest []image.Point)

HorizontalLine takes an index of a horizontal line and returns all points associated with the line in both grids. The points are sorted in increasing x-values.

func (*MorphGrid) Points

func (m *MorphGrid) Points(horizLine, vertLine int) (image.Point, image.Point, error)

Points returns the homogulous pair of points at the intersection of the two lines given by their indices.

func (*MorphGrid) RemovePoints

func (m *MorphGrid) RemovePoints(horizLine, vertLine int) error

RemovePoints removes the homogulous points that belong to the specified horizontal and vertical line. Returns an error if the operation is not able to complete successfully.

func (*MorphGrid) VerticalGridlineCount

func (m *MorphGrid) VerticalGridlineCount() int

VerticalGridlineCount determines the number of vertical grid lines that have been specified.

func (*MorphGrid) VerticalLine

func (m *MorphGrid) VerticalLine(index int) (source, dest []image.Point)

VerticalLine takes an index of a vertical line and returns all points associated with the line in both grids. The points are sorted in increasing y-values.