oiio

package module
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 20, 2022 License: MIT Imports: 6 Imported by: 0

README

OpenImageIO bindings for Go

GoDoc Travis Build Status

OpenImageIO is a library for reading and writing images, and a bunch of related classes, utilities, and applications. There is a particular emphasis on formats and functionality used in professional, large-scale animation and visual effects work for film. OpenImageIO is used extensively in animation and VFX studios all over the world, and is also incorporated into several commercial products.

Motivation

While there are other image processing bindings available, OpenImageIO is a common image processing solution to the Visual Effects industry, with specific support for concepts like EXR, deep compositing, OpenColorIO support, textures, and subimages. It isn't neccessarily the fastest solution, but it is comprehensive, and useful to VFX pipelines.

Compatibility

Tested against OpenImageIO 1.4.x - 1.6.x

Support for >= 1.7.x is in progress.

API Status

There is pretty decent exposure of the "Image*" APIs thus far, as well as the ColorConfig API. Because OIIO is a fairly large library, not every aspect of the APIs have been wrapped yet. It has mainly been driven by use-cases.

If you find something that you need is missing, feel free to submit a feature request, or better yet, fork and send a merge request :-)

Requirements

Installation

This package assumes that OpenImageIO/Boost is installed to the standard /usr/local location.

Default install:

go get github.com/justinfx/openimageigo

If you have installed OpenImageIO to a custom location, you will need to tell CGO where to find the headers and libs:

export CGO_CPPFLAGS="-I/path/to/include"
export CGO_LDFLAGS="-L/path/to/lib"

Or just prefixing the install:

CGO_CPPFLAGS="-I/usr/local/include" CGO_LDFLAGS="-L/usr/local/lib" go get github.com/justinfx/openimageigo

Documentation

Overview

OpenImageIO bindings

https://sites.google.com/site/openimageio/home

OpenImageIO is a library for reading and writing images, and a bunch of related classes, utilities, and applications. There is a particular emphasis on formats and functionality used in professional, large-scale animation and visual effects work for film. OpenImageIO is used extensively in animation and VFX studios all over the world, and is also incorporated into several commercial products.

Index

Examples

Constants

View Source 
const (
	// Let OIIO choose the best filter
	FilterDefault = ""
	// Let OIIO choose the best filter and filter width
	FilterDefaultWidth = 0.0
	// Use a default system font
	FontNameDefault = ""
	// Use the global OIIO-determined thread count
	GlobalThreads = 0
)

Variables

This section is empty.

Functions

func Add 

func Add(dst, a, b *ImageBuf, opts ...AlgoOpts) error

For all pixels and channels within the designated region, set dst to the sum of image A and image B. All of the images must have the same number of channels.

func AddValue 

func AddValue(dst, src *ImageBuf, value float32, opts ...AlgoOpts) error

For all pixels and channels within the designated region, set dst to the sum of image src and float value (added to all channels). All of the images must have the same number of channels.

func AddValues 

func AddValues(dst, src *ImageBuf, values []float32, opts ...AlgoOpts) error

For all pixels and channels within the designated region, set dst to the sum of image src and per-channel float slice values. All of the images must have the same number of channels.

func ChannelAppend 

func ChannelAppend(dst, a, b *ImageBuf, opts ...AlgoOpts) error

ChannelAppend appends the channels of A and B together into dst over the region of interest. If a roi is passed, it will be interpreted as being the union of the pixel windows of A and B (and all channels of both images). If dst is not already initialized to a size, it will be resized to be big enough for the region.

func Channels 

func Channels(dst, src *ImageBuf, nchannels int, opts ...*ChannelOpts) error

Generic channel shuffling: copy src to dst, but with channels in the order specified by ChannelOpts.Order[0..nchannels-1]. Does not support in-place operation.

See ChannelOpts docs for more details on the options.

func Checker 

func Checker(dst *ImageBuf, width, height, depth int, color1, color2 []float32,
	xoffset, yoffset, zoffset int, opts ...AlgoOpts) error

Checker sets the pixels in the destination image within the specified region to a checkerboard pattern with origin given by the offset values, checker size given by the width, height, depth values, and alternating between color1 and color2. The colors must contain enough values for all channels in the image.

func Checker2D 

func Checker2D(dst *ImageBuf, width, height int, color1, color2 []float32,
	xoffset, yoffset int, opts ...AlgoOpts) error

Checker2D sets the pixels in the destination image within the specified region to a checkerboard pattern with origin given by the offset values, checker size given by the width and height values, and alternating between color1 and color2. The colors must contain enough values for all channels in the image.

Example: 

// Create a new 640x480 RGB image, fill it with a two-toned gray
// checkerboard, the checkers being 64x64 pixels each.
spec := NewImageSpecSize(640, 480, 3, TypeFloat)
dark := []float32{0.1, 0.1, 0.1}
light := []float32{0.4, 0.4, 0.4}
Checker(spec, 64, 64, dark, light, 0, 0)

func ColorConvert 

func ColorConvert(dst, src *ImageBuf, from, to string, unpremult bool, opts ...AlgoOpts) error

Copy pixels within the ROI from src to dst, applying a color transform. If dst is not yet initialized, it will be allocated to the same size as specified by roi. If roi is not defined it will be all of dst, if dst is defined, or all of src, if dst is not yet defined. In-place operations (dst == src) are supported. If unpremult is true, unpremultiply before color conversion, then premultiply after the color conversion. You may want to use this flag if your image contains an alpha channel. Works with all data types.

func ColorConvertProcessor 

func ColorConvertProcessor(dst, src *ImageBuf, cp *ColorProcessor, unpremult bool, opts ...AlgoOpts) error

Copy pixels within the ROI from src to dst, applying a color transform. If dst is not yet initialized, it will be allocated to the same size as specified by roi. If roi is not defined it will be all of dst, if dst is defined, or all of src, if dst is not yet defined. In-place operations (dst == src) are supported. If unpremult is true, unpremultiply before color conversion, then premultiply after the color conversion. You may want to use this flag if your image contains an alpha channel. Works with all data types.

func ComputePixelHashSHA1 

func ComputePixelHashSHA1(src *ImageBuf, extraInfo string, blockSize int, opts ...AlgoOpts) string

ComputePixelHashSHA1 computes the SHA-1 byte hash for all the pixels in the specifed region of the image. If blocksize > 0, the function will compute separate SHA-1 hashes of each blocksize batch of scanlines, then return a hash of the individual hashes. This is just as strong a hash, but will NOT match a single hash of the entire image (blocksize == 0). But by breaking up the hash into independent blocks, we can parallelize across multiple threads, given by nthreads. The extrainfo provides additional text that will be incorporated into the hash.

func ConstantColors 

func ConstantColors(src *ImageBuf, opts ...AlgoOpts) []float32

ConstantColors returns a slice of the constant pixel values of all channels within either the src image, or the specific channel range of the given ROI. If the image does not have constant colors in the given channel range, a nil value is returned.

func Crop 

func Crop(dst, src *ImageBuf, opts ...AlgoOpts) error

Crop resets dst to be the specified region of src. Note that the crop operation does not actually move the pixels on the image plane or adjust the full/display window; it merely restricts which pixels are copied from src to dst. (Note the difference compared to Cut()).

func Cut 

func Cut(dst, src *ImageBuf, opts ...AlgoOpts) error

Cut assigns to dst the designated region of src, but shifted to be at the (0,0) origin, and with the full/display resolution set to be identical to the data region.

The nthreads AlgoOpts specifies how many threads (potentially) may be used, but it's not a guarantee. If nthreads == 0, it will use the global OIIO attribute "nthreads". If nthreads == 1, it guarantees that it will not launch any new threads.

func Fill 

func Fill(dst *ImageBuf, values []float32, opts ...AlgoOpts) error

Fill sets the pixels in the destination image within the specified region to the values in []values. The values slice must point to at least chend values, or the number of channels in the image, whichever is smaller.

func Flatten added in v1.2.1 

func Flatten(dst, src *ImageBuf, opts ...AlgoOpts) error

Set dst to the flattened composite of deep image src. That is, it converts a deep image to a simple flat image by front-to-back compositing the samples within each pixel. If src is already a non- deep/flat image, it will just copy pixel values from src to dst. If dst is not already an initialized ImageBuf, it will be sized to match src (but made non-deep).

'roi' specifies the region of dst's pixels which will be computed; existing pixels outside this range will not be altered. If not specified, the default ROI value will be the pixel data window of src.

func Flip 

func Flip(dst, src *ImageBuf, opts ...AlgoOpts) error

Flip copies src (or a subregion of src) to the corresponding pixels of dst, but with the scanlines exchanged vertically.

func Flipflop 

func Flipflop(dst, src *ImageBuf, opts ...AlgoOpts) error

Flipflop copies src (or a subregion of src to the corresponding pixels of dst, but with both the rows exchanged vertically and the columns exchanged horizontally (this is equivalent to a 180 degree rotation).

func Flop 

func Flop(dst, src *ImageBuf, opts ...AlgoOpts) error

Flop copies src (or a subregion of src) to the corresponding pixels of dst, but with the columns exchanged horizontally.

func IsConstantChannel 

func IsConstantChannel(src *ImageBuf, channel int, val float32, opts ...AlgoOpts) bool

IsConstantChannel returns true if all pixels of src within the ROI have the given channel value val

func IsConstantColor 

func IsConstantColor(src *ImageBuf, opts ...AlgoOpts) bool

IsConstantColor returns true if all pixels of src within the ROI have the same values (for the subset of channels described by roi)

func IsMonochrome 

func IsMonochrome(src *ImageBuf, opts ...AlgoOpts) bool

IsMonochrome returns true if the image is monochrome within the ROI, that is, for all pixels within the region, do all channels [roi.chbegin, roi.chend) have the same value? If roi is not defined (the default), it will be understood to be all of the defined pixels and channels of source.

func Mul 

func Mul(dst, a, b *ImageBuf, opts ...AlgoOpts) error

For all pixels within the designated region, multiply the pixel values of image A by image B (channel by channel), putting the product in dst. All of the images must have the same number of channels.

func MulValue 

func MulValue(dst, src *ImageBuf, value float32, opts ...AlgoOpts) error

For all pixels within the designated region, multiply the pixel values of image A by float value B (applied to all channels), putting the product in dst. All of the images must have the same number of channels.

func MulValues 

func MulValues(dst, src *ImageBuf, values []float32, opts ...AlgoOpts) error

For all pixels within the designated region, multiply the pixel values of image A by per-channel float array, putting the product in dst. All of the images must have the same number of channels.

func Over 

func Over(dst, a, b *ImageBuf, opts ...AlgoOpts) error

Over sets dst to the composite of A over B using the Porter/Duff definition of "over", returning true upon success and false for any of a variety of failures (as described below).

A and B (and dst, if already defined/allocated) must have valid alpha channels identified by their ImageSpec alpha_channel field. If A or B do not have alpha channels (as determined by those rules) or if the number of non-alpha channels do not match between A and B, Over() will fail.

If dst is not already an initialized ImageBuf, it will be sized to encompass the minimal rectangular pixel region containing the union of the defined pixels of A and B, and with a number of channels equal to the number of non-alpha channels of A and B, plus an alpha channel. However, if dst is already initialized, it will not be resized, and the "over" operation will apply to its existing pixel data window. In this case, dst must have an alpha channel designated and must have the same number of non-alpha channels as A and B, otherwise it will fail.

'roi' AlgoOpts specifies the region of dst's pixels which will be computed; existing pixels outside this range will not be altered. If not specified, the default ROI value will be interpreted as a request to apply "A over B" to the entire region of dst's pixel data.

A, B, and dst need not perfectly overlap in their pixel data windows; pixel values of A or B that are outside their respective pixel data window will be treated as having "zero" (0,0,0...) value.

The nthreads AlgoOpts specifies how many threads (potentially) may be used, but it's not a guarantee. If nthreads == 0, it will use the global OIIO attribute "nthreads". If nthreads == 1, it guarantees that it will not launch any new threads.

Example 
srcSpec := NewImageSpecSize(16, 16, 4, TypeFloat)
srcSpec.SetAlphaChannel(3)

srcA, _ := NewImageBufSpec(srcSpec)
srcB, _ := NewImageBufSpec(srcSpec)

// Red with 50% alpha
Fill(srcA, []float32{1.0, 0.0, 0.0, 0.5})
// Blue with solid alpha
Fill(srcB, []float32{0.0, 0.0, 1.0, 1.0})

// Make sure the foreground image is premult
Premult(srcA, srcA)

dst := NewImageBuf()
Over(dst, srcA, srcB)

Output:

func Paste 

func Paste(dst, src *ImageBuf, xbegin, ybegin, zbegin, chbegin int, opts ...AlgoOpts) error

Copy into dst, beginning at (xbegin, ybegin, zbegin, chbegin), the pixels of src described by roi. If roi is nil, the entirety of src will be used.

func Paste2D 

func Paste2D(dst, src *ImageBuf, xbegin, ybegin int, opts ...AlgoOpts) error

Copy into dst, beginning at (xbegin, ybegin), the pixels of src described by roi. If roi is nil, the entirety of src will be used.

func Premult 

func Premult(dst, src *ImageBuf, opts ...AlgoOpts) error

Premult copies pixels from src to dst, and in the process multiply all color channels (those not alpha or z) by the alpha value, to "premultiply" them. This presumes that the image starts of as "unassociated alpha" a.k.a. "non-premultipled." The alterations are restricted to the pixels and channels of the supplied ROI (which defaults to all of src). This is just a copy if there is no identified alpha channel (and a no-op if dst and src are the same image).

func RenderTextColor 

func RenderTextColor(dst *ImageBuf, x, y int, text string, fontSize int, fontName string, color []float32) error

RenderTextColor renders a text string into image dst, essentially doing an "over" of the character into the existing pixel data. The baseline of the first character will start at position (x,y), and with a nominal height of fontSize (in pixels). The font is given by fontName as either a full pathname to the font file, or a font basename which can be found in the standard system font locations. If an empty string is provided or font is not found, it defaults to some reasonable system font if not supplied at all. The characters will be drawn in opaque white (1.0,1.0,...) in all channels, unless color is supplied (and is expected to point to a float slice of length at least equal to R.Spec().NumChannels).

func Resample 

func Resample(dst, src *ImageBuf, interpolate bool, opts ...AlgoOpts) error

Set dst, over the region of interest, to be a resampled version of the corresponding portion of src (mapping such that the "full" image window of each correspond to each other, regardless of resolution). Unlike Resize(), Resample does not take a filter; it just samples either with a bilinear interpolation (if interpolate is true, the default) or uses the single "closest" pixel (if interpolate is false). This makes it a lot faster than a proper Resize(), though obviously with lower quality (aliasing when downsizing, pixel replication when upsizing). Works on all pixel data types.

func Resize 

func Resize(dst, src *ImageBuf, opts ...AlgoOpts) error

Set dst, over the region of interest, to be a resized version of the corresponding portion of src (mapping such that the "full" image window of each correspond to each other, regardless of resolution).

Default high-quality filters are used: blackman-harris when upsizing, lanczos3 when downsizing

The nthreads AlgoOpts specifies how many threads (potentially) may be used, but it's not a guarantee. If nthreads == 0, it will use the global OIIO attribute "nthreads". If nthreads == 1, it guarantees that it will not launch any new threads.

func ResizeFilter 

func ResizeFilter(dst, src *ImageBuf, filter string, filterWidth float32, opts ...AlgoOpts) error

Set dst, over the region of interest, to be a resized version of the corresponding portion of src (mapping such that the "full" image window of each correspond to each other, regardless of resolution).

The filter is used to weight the src pixels falling underneath it for each dst pixel. The caller may specify a reconstruction filter by name and width (expressed in pixels unts of the dst image), or ResizeFilter() will choose a reasonable default high-quality default filter (blackman-harris when upsizing, lanczos3 when downsizing) if the empty string is passed or if filterWidth is 0.

The nthreads AlgoOpts specifies how many threads (potentially) may be used, but it's not a guarantee. If nthreads == 0, it will use the global OIIO attribute "nthreads". If nthreads == 1, it guarantees that it will not launch any new threads.

func Sub 

func Sub(dst, a, b *ImageBuf, opts ...AlgoOpts) error

For all pixels and channels within the designated region, subtract image B from image A. All of the images must have the same number of channels.

func SubValue 

func SubValue(dst, src *ImageBuf, value float32, opts ...AlgoOpts) error

For all pixels and channels within the designated region, subtract float value (subtracted from all channels) from image src. All of the images must have the same number of channels.

func SubValues 

func SubValues(dst, src *ImageBuf, values []float32, opts ...AlgoOpts) error

For all pixels and channels within the designated region, subtract per-channel float slice B from image src. All of the images must have the same number of channels.

func SupportsOpenColorIO 

func SupportsOpenColorIO() bool

Return if OpenImageIO was built with OCIO support

func Transpose 

func Transpose(dst, src *ImageBuf, opts ...AlgoOpts) error

Transpose copies src (or a subregion of src to the corresponding transposed (x$y) pixels

func Unpremult 

func Unpremult(dst, src *ImageBuf, opts ...AlgoOpts) error

Unpremult copies pixels from src to dst, and in the process divide all color channels (those not alpha or z) by the alpha value, to "un-premultiply" them. This presumes that the image starts of as "associated alpha" a.k.a. "premultipled." The alterations are restricted to the pixels and channels of the supplied ROI (which defaults to all of src). Pixels in which the alpha channel is 0 will not be modified (since the operation is undefined in that case). This is just a copy if there is no identified alpha channel (and a no-op if dst and src are the same image).

func Zero 

func Zero(dst *ImageBuf, opts ...AlgoOpts) error

Zero out (set to 0, black) the image region. Only the pixels (and channels) in dst that are specified by roi will be altered; the default roi is to alter all the pixels in dst. If dst is uninitialized, it will be resized to be a float ImageBuf large enough to hold the region specified by roi. It is an error to pass both an uninitialied dst and an undefined roi. Works on all pixel data types.

Types

type AlgoOpts 

type AlgoOpts struct {
	// The Region of interest to use when applying the operation.
	// Some algorithms require either an ROI or to fallback on the
	// spec of the ImageBuf being given.
	ROI *ROI
	// The Threads parameter specifies how many threads (potentially) may
	// be used, but it's not a guarantee.
	// If Threads == 0, it will use the global OIIO attribute "threads".
	// If Threads == 1, it guarantees that it will
	// not launch any new threads.
	Threads int
}

AlgoOpts allows common arguments to be passed to algorithm functions.

type ChannelOpts 

type ChannelOpts struct {
	Order        []int32
	Values       []float32
	NewNames     []string
	ShuffleNames bool
}

ChannelOpts are options that can be passed to the Channels() function

For any channel in which ChannelOpts.Order[i] < 0, it will just make dst channel i be a constant value set to ChannelOpts.Values[i] (if ChannelOpts.Values is not nil) or 0.0 (if ChannelOpts.Values is nil). If ChannelOpts.Order is nil, it will be interpreted as {0, 1, ..., nchannels-1}, mean- ing that it's only renaming channels, not reordering them. If ChannelOpts.NewNames is not nil, it points to a list of new channel names. Channels for which ChannelOpts.NewNames[i] is the empty string (or all channels, if ChannelOpts.NewNames == nil) will be named as follows: If ChannelOpts.ShuffleNames is false, the result- ing dst image will have default channel names in the usual order ("R", "G", etc.), but if ChannelOpts.ShuffleNames is true, the names will be taken from the corresponding channels of the source image - be careful with this, shuffling both channel ordering and their names could result in no semantic change at all, if you catch the drift.

type ColorConfig 

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

Represents the set of all color transformations that are allowed. If OpenColorIO is enabled at build time, this configuration is loaded at runtime, allowing the user to have complete control of all color transformation math. ($OCIO) (See opencolorio.org for details). If OpenColorIO is not enabled at build time, a generic color configuration is provided for minimal color support.

NOTE: ColorConfig(s) and ColorProcessor(s) are potentially heavy-weight. Their construction / destruction should be kept to a minimum.

func NewColorConfig 

func NewColorConfig() (*ColorConfig, error)

If OpenColorIO is enabled at build time, initialize with the current color configuration. ($OCIO) If OpenColorIO is not enabled, this does nothing.

Multiple calls to this are inexpensive.

func NewColorConfigPath 

func NewColorConfigPath(path string) (*ColorConfig, error)

If OpenColorIO is enabled at build time, initialize with the specified color configuration (.ocio) file If OpenColorIO is not enabled, this will result in an error.

Multiple calls to this are potentially expensive.

func (*ColorConfig) ColorSpaceNameByIndex 

func (c *ColorConfig) ColorSpaceNameByIndex(index int) string

Return the name of the colorspace at a given index

func (*ColorConfig) ColorSpaceNameByRole 

func (c *ColorConfig) ColorSpaceNameByRole(role string) string

Get the name of the color space representing the named role, or empty string if none could be identified.

func (*ColorConfig) CreateColorProcessor 

func (c *ColorConfig) CreateColorProcessor(inColorSpace, outColorSpace string) (*ColorProcessor, error)

Given the specified input and output ColorSpace, construct the processor. It is possible that this will return nil and an error, if the inputColorSpace doesnt exist, the outputColorSpace doesn't exist, or if the specified transformation is illegal (for example, it may require the inversion of a 3D-LUT, etc). When the user is finished with a ColorProcess, ColorProcess.Destroy() should be called. ColorProcessor(s) remain valid even if the ColorConfig that created them no longer exists.

Multiple calls to this are potentially expensive, so you should call once to create a ColorProcessor to use on an entire image (or multiple images), NOT for every scanline or pixel separately!

func (*ColorConfig) Destroy added in v1.1.0 

func (c *ColorConfig) Destroy()

Destroy the object immediately instead of waiting for GC.

func (*ColorConfig) DisplayNameByIndex 

func (c *ColorConfig) DisplayNameByIndex(index int) string

Return the name of the display at a given index

func (*ColorConfig) LookNameByIndex 

func (c *ColorConfig) LookNameByIndex(index int) string

Return the name of the look at a given index

func (*ColorConfig) NumColorSpaces 

func (c *ColorConfig) NumColorSpaces() int

Get the number of ColorSpace(s) defined in this configuration

func (*ColorConfig) NumDisplays 

func (c *ColorConfig) NumDisplays() int

Get the number of displays defined in this configuration

func (*ColorConfig) NumLooks 

func (c *ColorConfig) NumLooks() int

Get the number of Looks defined in this configuration

func (*ColorConfig) NumViews 

func (c *ColorConfig) NumViews(displayName string) int

Get the number of displays defined in this configuration

func (*ColorConfig) ViewNameByIndex 

func (c *ColorConfig) ViewNameByIndex(displayName string, index int) string

Get the name of a view at a specific index of a display

type ColorProcessor 

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

The ColorProcessor encapsulates a baked color transformation, suitable for application to raw pixels, or ImageBuf(s). These are generated using ColorConfig.CreateColorProcessor, and referenced in ImageBufAlgo (amongst other places)

func (*ColorProcessor) Destroy added in v1.1.0 

func (c *ColorProcessor) Destroy()

Destroy the object immediately instead of waiting for GC.

type IBStorage 

type IBStorage int

Description of where the pixels live for this ImageBuf 

const (
	// Derive the file format from the file path name (empty string)
	FileFormatAuto = ""

	IBStorageLocalBuffer   IBStorage = C.IBSTORAGE_LOCALBUFFER
	IBStorageAppBuffer     IBStorage = C.IBSTORAGE_APPBUFFER
	IBStorageImageCache    IBStorage = C.IBSTORAGE_IMAGECACHE
	IBStorageUninitialized IBStorage = C.IBSTORAGE_UNINITIALIZED
)

type ImageBuf 

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

An ImageBuf is a simple in-memory representation of a 2D image. It uses ImageInput and ImageOutput underneath for its file I/O, and has simple routines for setting and getting individual pixels, that hides most of the details of memory layout and data representation (translating to/from float automatically).

func NewImageBuf 

func NewImageBuf() *ImageBuf

Construct an empty/uninitialized ImageBuf. This is relatively useless until you call reset().

func NewImageBufPath 

func NewImageBufPath(path string) (*ImageBuf, error)

Construct an ImageBuf to read the named image - but don't actually read it yet! The image will actually be read when other methods need to access the spec and/or pixels, or when an explicit call to init_spec() or read() is made, whichever comes first.

Uses the global/shared ImageCache.

func NewImageBufPathCache 

func NewImageBufPathCache(path string, cache *ImageCache) (*ImageBuf, error)

Construct an ImageBuf to read the named image - but don't actually read it yet! The image will actually be read when other methods need to access the spec and/or pixels, or when an explicit call to init_spec() or read() is made, whichever comes first.

Uses an explicitly passed ImageCache

func NewImageBufSpec 

func NewImageBufSpec(spec *ImageSpec) (*ImageBuf, error)

Construct an Imagebuf given a proposed spec describing the image size and type, and allocate storage for the pixels of the image (whose values will be uninitialized).

func (*ImageBuf) CachedPixels 

func (i *ImageBuf) CachedPixels() bool

func (*ImageBuf) Clear 

func (i *ImageBuf) Clear()

Restore the ImageBuf to an uninitialized state.

func (*ImageBuf) Copy 

func (i *ImageBuf) Copy(src *ImageBuf) error

Try to copy the pixels and metadata from src to this, returning true upon success and false upon error/failure.

If the previous state of this was uninitialized, owning its own local pixel memory, or referring to a read-only image backed by ImageCache, then local pixel memory will be allocated to hold the new pixels and the call always succeeds unless the memory cannot be allocated.

If this previously referred to an app-owned memory buffer, the memory cannot be re-allocated, so the call will only succeed if the app-owned buffer is already the correct resolution and number of channels. The data type of the pixels will be converted automatically to the data type of the app buffer.

func (*ImageBuf) CopyMetadata 

func (i *ImageBuf) CopyMetadata(src *ImageBuf) error

Copy all the metadata from src to this (except for pixel data resolution, channel information, and data format).

func (*ImageBuf) CopyPixels 

func (i *ImageBuf) CopyPixels(src *ImageBuf) error

Copy the pixel data from src to this, automatically converting to the existing data format of this. It only copies pixels in the overlap regions (and channels) of the two images; pixel data in this that do exist in src will be set to 0, and pixel data in src that do not exist in this will not be copied.

func (*ImageBuf) Deep 

func (i *ImageBuf) Deep() bool

Does this ImageBuf store deep data?

func (*ImageBuf) Destroy added in v1.1.0 

func (i *ImageBuf) Destroy()

Destroy the object immediately instead of waiting for GC.

func (*ImageBuf) FileFormatName 

func (i *ImageBuf) FileFormatName() string

Return the name of the image file format of the disk file we read into this image. Returns an empty string if this image was not the result of a Read().

func (*ImageBuf) GetFloatPixels 

func (i *ImageBuf) GetFloatPixels() ([]float32, error)

GetFloatPixels retrieves the rectangle of pixels spanning the entire image, at the current subimage and MIP-map level, storing the float pixel values in a []float32

func (*ImageBuf) GetPixelRegion 

func (i *ImageBuf) GetPixelRegion(roi *ROI, format TypeDesc) (interface{}, error)

GetPixelRegion retrieves the rectangle of pixels defined by an ROI, at the current subimage and MIP-map level, storing the pixel values in a slice that has been casted to an interface, and in the pixel format type described by 'format'.

The underlying type of data is determined by the given TypeDesc. Returned interface{} will be: 

TypeUint8   => []uint8
TypeInt8    => []int8
TypeUint16  => []uint16
TypeInt16   => []int16
TypeUint    => []uint
TypeInt     => []int
TypeUint64  => []uint64
TypeInt64   => []int64
TypeHalf    => []float32
TypeFloat   => []float32
TypeDouble  => []float64

Example: 

val, err := buf.GetPixelRegion(roi, TypeFloat)
if err != nil {
    panic(err.Error())
}
floatPixels := val.([]float32)

func (*ImageBuf) GetPixels 

func (i *ImageBuf) GetPixels(format TypeDesc) (interface{}, error)

GetPixels retrieves the rectangle of pixels spanning the entire image, at the current subimage and MIP-map level, storing the pixel values in a slice that has been casted to an interface, and in the pixel format type described by 'format'.

The underlying type of data is determined by the given TypeDesc. Returned interface{} will be: 

TypeUint8   => []uint8
TypeInt8    => []int8
TypeUint16  => []uint16
TypeInt16   => []int16
TypeUint    => []uint
TypeInt     => []int
TypeUint64  => []uint64
TypeInt64   => []int64
TypeHalf    => []float32
TypeFloat   => []float32
TypeDouble  => []float64

Example: 

val, err := buf.GetPixels(TypeFloat)
if err != nil {
    panic(err.Error())
}
floatPixels := val.([]float32)

func (*ImageBuf) ImageCache 

func (i *ImageBuf) ImageCache() *ImageCache

Return the ImageCache in which backs this ImageBuf

func (*ImageBuf) InitSpec 

func (i *ImageBuf) InitSpec(filename string, subimage, miplevel int) error

Initialize this ImageBuf with the named image file, and read its header to fill out the spec correctly. Return true if this succeeded, false if the file could not be read. But don't allocate or read the pixels.

func (*ImageBuf) Initialized 

func (i *ImageBuf) Initialized() bool

Is this ImageBuf object initialized?

func (*ImageBuf) LastError 

func (i *ImageBuf) LastError() error

Return the last error generated by API calls. An nil error will be returned if no error has occured.

func (*ImageBuf) MipLevel 

func (i *ImageBuf) MipLevel() int

Return the index of the miplevel are we currently viewing

func (*ImageBuf) Name 

func (i *ImageBuf) Name() string

Return the name of this image.

func (*ImageBuf) NativeSpec 

func (i *ImageBuf) NativeSpec() *ImageSpec

Return a reference to the "native" image spec (that describes the file, which may be slightly different than the spec of the ImageBuf, particularly if the IB is backed by an ImageCache that is imposing some particular data format or tile size).

func (*ImageBuf) NumChannels 

func (i *ImageBuf) NumChannels() int

Return the number of color channels in the image.

func (*ImageBuf) NumMipLevels 

func (i *ImageBuf) NumMipLevels() int

Return the number of miplevels of the current subimage.

func (*ImageBuf) NumSubImages 

func (i *ImageBuf) NumSubImages() int

Return the number of subimages in the file.

func (*ImageBuf) Orientation 

func (i *ImageBuf) Orientation() int

By default, image pixels are ordered from the top of the display to the bottom, and within each scanline, from left to right (i.e., the same ordering as English text and scan progression on a CRT). But the "Orientation" field can suggest that it should be displayed with a different orientation, according to the TIFF/EXIF conventions: 

1 normal (top to bottom, left to right)
2 flipped horizontally (top to botom, right to left)
3 rotate 180 (bottom to top, right to left)
4 flipped vertically (bottom to top, left to right)
5 transposed (left to right, top to bottom)
6 rotated 90 clockwise (right to left, top to bottom)
7 transverse (right to left, bottom to top)
8 rotated 90 counter-clockwise (left to right, bottom to top)

func (*ImageBuf) OrientedFullHeight 

func (i *ImageBuf) OrientedFullHeight() int

func (*ImageBuf) OrientedFullWidth 

func (i *ImageBuf) OrientedFullWidth() int

func (*ImageBuf) OrientedFullX 

func (i *ImageBuf) OrientedFullX() int

func (*ImageBuf) OrientedFullY 

func (i *ImageBuf) OrientedFullY() int

func (*ImageBuf) OrientedHeight 

func (i *ImageBuf) OrientedHeight() int

func (*ImageBuf) OrientedWidth 

func (i *ImageBuf) OrientedWidth() int

func (*ImageBuf) OrientedX 

func (i *ImageBuf) OrientedX() int

func (*ImageBuf) OrientedY 

func (i *ImageBuf) OrientedY() int

func (*ImageBuf) PixelType 

func (i *ImageBuf) PixelType() TypeDesc

func (*ImageBuf) PixelsValid 

func (i *ImageBuf) PixelsValid() bool

func (*ImageBuf) ROI 

func (i *ImageBuf) ROI() *ROI

Return pixel data window for this ImageBuf as a ROI.

func (*ImageBuf) ROIFull 

func (i *ImageBuf) ROIFull() *ROI

Return full/display window for this ImageBuf as a ROI.

func (*ImageBuf) Read 

func (i *ImageBuf) Read(force bool) error

Read the file from disk. Generally will skip the read if we've already got a current version of the image in memory, unless force==true. This uses ImageInput underneath, so will read any file format for which an appropriate imageio plugin can be found.

func (*ImageBuf) ReadCallback 

func (i *ImageBuf) ReadCallback(force bool, progress *ProgressCallback) error

Read the file from disk. Generally will skip the read if we've already got a current version of the image in memory, unless force==true. This uses ImageInput underneath, so will read any file format for which an appropriate imageio plugin can be found.

This call optionally supports passing a callback pointer to both track the progress, and to optionally abort the processing. The callback function will receive a float32 value indicating the percentage done of the processing, and should return true if the process should abort, and false if it should continue.

func (*ImageBuf) ReadFormatCallback 

func (i *ImageBuf) ReadFormatCallback(force bool, convert TypeDesc, progress *ProgressCallback) error

Read the file from disk. Generally will skip the read if we've already got a current version of the image in memory, unless force==true. This uses ImageInput underneath, so will read any file format for which an appropriate imageio plugin can be found.

Specify a specific conversion format or TypeUnknown for automatic handling.

This call optionally supports passing a callback pointer to both track the progress, and to optionally abort the processing. The callback function will receive a float32 value indicating the percentage done of the processing, and should return true if the process should abort, and false if it should continue.

func (*ImageBuf) ReadSubImage added in v1.3.0 

func (i *ImageBuf) ReadSubImage(subimage, miplevel int, force bool) error

Read the file from disk. Generally will skip the read if we've already got a current version of the image in memory, unless force==true. This uses ImageInput underneath, so will read any file format for which an appropriate imageio plugin can be found.

func (*ImageBuf) ReadSubImageCallback added in v1.3.0 

func (i *ImageBuf) ReadSubImageCallback(subimage, miplevel int, force bool, progress *ProgressCallback) error

Read the file from disk. Generally will skip the read if we've already got a current version of the image in memory, unless force==true. This uses ImageInput underneath, so will read any file format for which an appropriate imageio plugin can be found.

This call optionally supports passing a callback pointer to both track the progress, and to optionally abort the processing. The callback function will receive a float32 value indicating the percentage done of the processing, and should return true if the process should abort, and false if it should continue.

func (*ImageBuf) ReadSubImageFormatCallback added in v1.3.0 

func (i *ImageBuf) ReadSubImageFormatCallback(subimage, miplevel int, force bool, convert TypeDesc, progress *ProgressCallback) error

Read the file from disk. Generally will skip the read if we've already got a current version of the image in memory, unless force==true. This uses ImageInput underneath, so will read any file format for which an appropriate imageio plugin can be found.

Specify a specific conversion format or TypeUnknown for automatic handling.

This call optionally supports passing a callback pointer to both track the progress, and to optionally abort the processing. The callback function will receive a float32 value indicating the percentage done of the processing, and should return true if the process should abort, and false if it should continue.

func (*ImageBuf) Reset added in v1.3.0 

func (i *ImageBuf) Reset(filename string, cache *ImageCache) error

Reset forgets all previous info, and resets this ImageBuf to a new image that is uninitialized (no pixel values, no size or spec). 'cache' may be nil, or can be a specific cache to use instead of the global.

func (*ImageBuf) ResetNameSpec added in v1.3.0 

func (i *ImageBuf) ResetNameSpec(filename string, spec *ImageSpec) error

ResetNameSpec forgets all previous info, and reset this ImageBuf to a blank image of the given name and dimensions.

func (*ImageBuf) ResetSpec added in v1.3.0 

func (i *ImageBuf) ResetSpec(spec *ImageSpec) error

ResetSpec forgets all previous info, and reset this ImageBuf to a blank image of the given dimensions.

func (*ImageBuf) ResetSubImage added in v1.3.0 

func (i *ImageBuf) ResetSubImage(filename string, subimage, miplevel int, cache *ImageCache, config *ImageSpec) error

ResetSubImage forgets all previous info, and resets this ImageBuf to a new image that is uninitialized (no pixel values, no size or spec). If 'config' is not nil, it points to an ImageSpec giving requests or special instructions to be passed on to the eventual ImageInput.Open() call. 'cache' may be nil, or can be a specific cache to use instead of the global.

func (*ImageBuf) SetFull 

func (i *ImageBuf) SetFull(xbegin, xend, ybegin, yend, zbegin, zend int)

Set the "full" (a.k.a. display) window to [xbegin,xend) x [ybegin,yend) x [zbegin,zend).

func (*ImageBuf) SetROIFull 

func (i *ImageBuf) SetROIFull(roi *ROI) error

Set full/display window for this ImageBuf to a ROI. Does NOT change the channels of the spec, regardless of newroi.

func (*ImageBuf) SetWriteFormat 

func (i *ImageBuf) SetWriteFormat(format TypeDesc)

Inform the ImageBuf what data format you'd like for any subsequent write().

func (*ImageBuf) SetWriteTiles 

func (i *ImageBuf) SetWriteTiles(width, height, depth int)

Inform the ImageBuf what tile size (or no tiling, for 0) for any subsequent Write*()

func (*ImageBuf) Spec 

func (i *ImageBuf) Spec() *ImageSpec

Return a reference to the image spec that describes the buffer.

func (*ImageBuf) SpecMod 

func (i *ImageBuf) SpecMod() *ImageSpec

Return a writable reference to the image spec that describes the buffer. Use with extreme caution! If you use this for anything other than adding attribute metadata, you are really taking your chances!

func (*ImageBuf) Storage 

func (i *ImageBuf) Storage() IBStorage

func (*ImageBuf) SubImage 

func (i *ImageBuf) SubImage() int

Return the index of the subimage are we currently viewing

func (*ImageBuf) Swap 

func (i *ImageBuf) Swap(other *ImageBuf) error

Swap with another ImageBuf.

func (*ImageBuf) WriteFile 

func (i *ImageBuf) WriteFile(filepath, fileformat string) error

Write the image to the named file and file format (fileformat=="" means to infer the type from the filename extension).

func (*ImageBuf) WriteFileProgress 

func (i *ImageBuf) WriteFileProgress(filepath, fileformat string, progress *ProgressCallback) error

Write the image to the named file and file format (fileformat=="" means to infer the type from the filename extension).

This call optionally supports passing a callback pointer to both track the progress, and to optionally abort the processing. The callback function will receive a float32 value indicating the percentage done of the processing, and should return true if the process should abort, and false if it should continue.

func (*ImageBuf) WriteImageOutput 

func (i *ImageBuf) WriteImageOutput(output *ImageOutput) error

Write the image to the open ImageOutput 'out'. Return true if all went ok, false if there were errors writing. It does NOT close the file when it's done (and so may be called in a loop to write a multi-image file).

func (*ImageBuf) WriteImageOutputProgress 

func (i *ImageBuf) WriteImageOutputProgress(output *ImageOutput, progress *ProgressCallback) error

Write the image to the open ImageOutput 'out'. Return true if all went ok, false if there were errors writing. It does NOT close the file when it's done (and so may be called in a loop to write a multi-image file).

This call optionally supports passing a callback pointer to both track the progress, and to optionally abort the processing. The callback function will receive a float32 value indicating the percentage done of the processing, and should return true if the process should abort, and false if it should continue.

func (*ImageBuf) XBegin 

func (i *ImageBuf) XBegin() int

Return the beginning (minimum) x coordinate of the defined image.

func (*ImageBuf) XEnd 

func (i *ImageBuf) XEnd() int

Return the end (one past maximum) x coordinate of the defined image.

func (*ImageBuf) XMax 

func (i *ImageBuf) XMax() int

Return the maximum x coordinate of the defined image.

func (*ImageBuf) XMin 

func (i *ImageBuf) XMin() int

Return the end (one past maximum) z coordinate of the defined image.

func (*ImageBuf) YBegin 

func (i *ImageBuf) YBegin() int

Return the beginning (minimum) y coordinate of the defined image

func (*ImageBuf) YEnd 

func (i *ImageBuf) YEnd() int

Return the end (one past maximum) y coordinate of the defined image.

func (*ImageBuf) YMax 

func (i *ImageBuf) YMax() int

Return the maximum y coordinate of the defined image.

func (*ImageBuf) YMin 

func (i *ImageBuf) YMin() int

Return the minimum y coordinate of the defined image.

func (*ImageBuf) ZBegin 

func (i *ImageBuf) ZBegin() int

Return the beginning (minimum) z coordinate of the defined image.

func (*ImageBuf) ZEnd 

func (i *ImageBuf) ZEnd() int

Return the end (one past maximum) z coordinate of the defined image.

func (*ImageBuf) ZMax 

func (i *ImageBuf) ZMax() int

Return the maximum z coordinate of the defined image.

func (*ImageBuf) ZMin 

func (i *ImageBuf) ZMin() int

Return the minimum z coordinate of the defined image.

type ImageCache 

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

Define an API to an abstract class that manages image files, caches of open file handles as well as tiles of pixels so that truly huge amounts of image data may be accessed by an application with low memory footprint.

func CreateImageCache 

func CreateImageCache(shared bool) *ImageCache

Create an ImageCache. *This should be freed by calling ImageCache.Destroy()*

If shared==true, it's intended to be shared with other like-minded owners in the same process who also ask for a shared cache.

If false, a private image cache will be created.

func (*ImageCache) Clear 

func (i *ImageCache) Clear()

Close everything, free resources, start from scratch.

func (*ImageCache) Destroy 

func (i *ImageCache) Destroy(teardown bool)

Destroy a ImageCache that was created using CreateImageCache(). When 'teardown' parameter is set to true, it will fully destroy even a "shared" ImageCache.

func (*ImageCache) GetStats 

func (i *ImageCache) GetStats(level int) string

Return the statistics output as a huge string. Suitable default for level == 1

func (*ImageCache) Invalidate 

func (i *ImageCache) Invalidate(filename string)

Invalidate any loaded tiles or open file handles associated with the filename, so that any subsequent queries will be forced to re-open the file or re-load any tiles (even those that were previously loaded and would ordinarily be reused). A client might do this if, for example, they are aware that an image being held in the cache has been updated on disk. This is safe to do even if other procedures are currently holding reference-counted tile pointers from the named image, but those procedures will not get updated pixels until they release the tiles they are holding.

func (*ImageCache) InvalidateAll 

func (i *ImageCache) InvalidateAll(force bool)

Invalidate all loaded tiles and open file handles. This is safe to do even if other procedures are currently holding reference-counted tile pointers from the named image, but those procedures will not get updated pixels until they release the tiles they are holding. If force is true, everything will be invalidated, no matter how wasteful it is, but if force is false, in actuality files will only be invalidated if their modification times have been changed since they were first opened.

func (*ImageCache) LastError 

func (i *ImageCache) LastError() error

Return the last error generated by API calls. An nil error will be returned if no error has occured.

func (*ImageCache) ResetStats 

func (i *ImageCache) ResetStats()

Reset most statistics to be as they were with a fresh ImageCache. Caveat emptor: this does not flush the cache itelf, so the resulting statistics from the next set of texture requests will not match the number of tile reads, etc., that would have resulted from a new ImageCache.

type ImageInput 

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

ImageInput abstracts the reading of an image file in a file format-agnostic manner.

func OpenImageInput 

func OpenImageInput(filename string) (*ImageInput, error)

Create an ImageInput subclass instance that is able to read the given file and open it, returning the opened ImageInput if successful. If it fails, return error.

func (*ImageInput) Close 

func (i *ImageInput) Close() error

Close an image that we are totally done with.

func (*ImageInput) CurrentMipLevel 

func (i *ImageInput) CurrentMipLevel() int

Returns the index of the MIPmap image that is currently being read. The highest-res MIP level (or the only level, if there is just one) is number 0.

func (*ImageInput) CurrentSubimage 

func (i *ImageInput) CurrentSubimage() int

CurrentSubimage returns the index of the subimage that is currently being read. The first subimage (or the only subimage, if there is just one) is number 0.

func (*ImageInput) Destroy added in v1.1.0 

func (i *ImageInput) Destroy()

Destroy the object immediately instead of waiting for GC.

func (*ImageInput) FormatName 

func (i *ImageInput) FormatName() string

Return the name of the format implemented by this image.

func (*ImageInput) LastError 

func (i *ImageInput) LastError() error

Return the last error generated by API calls. An nil error will be returned if no error has occured.

func (*ImageInput) Open 

func (i *ImageInput) Open(filename string) error

Open file with given name. Return true if the file was found and opened okay.

func (*ImageInput) ReadImage 

func (i *ImageInput) ReadImage() ([]float32, error)

Read the entire image of width * height * depth * channels into contiguous float32 pixels. Read tiles or scanlines automatically.

func (*ImageInput) ReadImageFormat 

func (i *ImageInput) ReadImageFormat(format TypeDesc, progress *ProgressCallback) (interface{}, error)

Read the entire image of width * height * depth * channels into contiguous pixels. Read tiles or scanlines automatically.

This call supports passing a callback pointer to both track the progress, and to optionally abort the processing. The callback function will receive a float32 value indicating the percentage done of the processing, and should return true if the process should abort, and false if it should continue.

The underlying type of data is determined by the given TypeDesc. Returned interface{} will be: 

TypeUint8   => []uint8
TypeInt8    => []int8
TypeUint16  => []uint16
TypeInt16   => []int16
TypeUint    => []uint
TypeInt     => []int
TypeUint64  => []uint64
TypeInt64   => []int64
TypeHalf    => []float32
TypeFloat   => []float32
TypeDouble  => []float64

Example: 

// Without a callback
val, err := in.ReadImageFormat(TypeFloat, nil)
if err != nil {
    panic(err.Error())
}
floatPixels := val.([]float32)

// With a callback
var cbk ProgressCallback = func(done float32) bool {
    fmt.Printf("Progress: %0.2f\n", done)
    // Keep processing (return true to abort)
    return false
}
val, _ = in.ReadImageFormat(TypeFloat, &cbk)
floatPixels = val.([]float32)

func (*ImageInput) ReadScanline 

func (i *ImageInput) ReadScanline(y, z int) ([]float32, error)

Read the scanline that includes pixels (*,y,z), converting if necessary from the native data format of the file into contiguous float32 pixels (z==0 for non-volume images). The size of the slice is: width * depth * channels

func (*ImageInput) ReadTile 

func (i *ImageInput) ReadTile(x, y, z int) ([]float32, error)

Read the tile whose upper-left origin is (x,y,z), converting if necessary from the native data format of the file into contiguous float32 pixels. The size of the slice is: tilewidth * tileheight * depth * channels (z==0 for non-volume images.)

func (*ImageInput) SeekMipLevel 

func (i *ImageInput) SeekMipLevel(subimage, miplevel int, newSpec *ImageSpec) bool

Seek to the given subimage and MIP-map level within the open image file. The first subimage of the file has index 0, the highest-resolution MIP level has index 0. Return true on success, false on failure (including that there is not a subimage or MIP level with the specified index). The new subimage's vital statistics are put in newspec (and also saved in ImageInpit.Spec()). The reader is expected to give the appearance of random access to subimages and MIP levels -- in other words, if it can't randomly seek to the given subimage/level, it should transparently close, reopen, and sequentially read through prior subimages and levels.

func (*ImageInput) SeekSubimage 

func (i *ImageInput) SeekSubimage(index int, newSpec *ImageSpec) bool

Seek to the given subimage within the open image file. The first subimage of the file has index 0. Return true on success, false on failure (including that there is not a subimage with the specified index). The new subimage's vital statistics are put in newspec (and also saved in ImageInput.Spec()). The reader is expected to give the appearance of random access to subimages -- in other words, if it can't randomly seek to the given subimage, it should transparently close, reopen, and sequentially read through prior subimages.

func (*ImageInput) Spec 

func (i *ImageInput) Spec() *ImageSpec

Return a reference to the image format specification of the current subimage/MIPlevel. Note that the contents of the spec are invalid before Open() or after Close(), and may change with a call to SeekSubImage().

func (*ImageInput) Supports 

func (i *ImageInput) Supports(feature string) bool

Given the name of a 'feature', return whether this ImageOutput supports output of images with the given properties. Feature names that ImageIO plugins are expected to recognize include: 

"tiles"          Is this format able to write tiled images?
"rectangles"     Does this plugin accept arbitrary rectangular
                   pixel regions, not necessarily aligned to
                   scanlines or tiles?
"random_access"  May tiles or scanlines be written in
                   any order (false indicates that they MUST
                   be in successive order).
"multiimage"     Does this format support multiple subimages
                   within a file?
"appendsubimage" Does this format support adding subimages one at
                   a time through open(name,spec,AppendSubimage)?
                   If not, then open(name,subimages,specs) must
                   be used instead.
"mipmap"         Does this format support multiple resolutions
                   for an image/subimage?
"volumes"        Does this format support "3D" pixel arrays?
"rewrite"        May the same scanline or tile be sent more than
                   once?  (Generally, this will be true for
                   plugins that implement interactive display.)
"empty"          Does this plugin support passing a NULL data
                   pointer to write_scanline or write_tile to
                   indicate that the entire data block is zero?
"channelformats" Does the plugin/format support per-channel
                   data formats?
"displaywindow"  Does the format support display ("full") windows
                    distinct from the pixel data window?
"origin"         Does the format support a nonzero x,y,z
                    origin of the pixel data window?
"negativeorigin" Does the format support negative x,y,z
                    and full_{x,y,z} origin values?
"deepdata"       Deep (multi-sample per pixel) data

Note that main advantage of this approach, versus having separate individual supports_foo() methods, is that this allows future expansion of the set of possible queries without changing the API, adding new entry points, or breaking linkage compatibility.

func (*ImageInput) ValidFile 

func (i *ImageInput) ValidFile(filename string) bool

Return true if the named file is file of the type for this ImageInput. The implementation will try to determine this as efficiently as possible, in most cases much less expensively than doing a full Open(). Note that a file can appear to be of the right type (i.e., ValidFIle() returning true) but still fail a subsequent call to Open(), such as if the contents of the file are truncated, nonsensical, or otherwise corrupted.

type ImageOutput 

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

ImageOutput abstracts the writing of an image file in a file format-agnostic manner.

func OpenImageOutput 

func OpenImageOutput(filename string) (*ImageOutput, error)

Create an ImageOutput that will write to a file, with the format inferred from the extension of the name. This just creates the ImageOutput, it does not open the file.

func (*ImageOutput) Destroy added in v1.1.0 

func (i *ImageOutput) Destroy()

Destroy the object immediately instead of waiting for GC.

func (*ImageOutput) FormatName 

func (i *ImageOutput) FormatName() string

Return the name of the format implemented by this image.

func (*ImageOutput) LastError 

func (i *ImageOutput) LastError() error

Return the last error generated by API calls. An nil error will be returned if no error has occured.

func (*ImageOutput) Spec 

func (i *ImageOutput) Spec() *ImageSpec

Return a reference to the image format specification of the current subimage/MIPlevel. Note that the contents of the spec will be empty unless it is further added to it

func (*ImageOutput) Supports 

func (i *ImageOutput) Supports(feature string) bool

Given the name of a 'feature', return whether this ImageOutput supports output of images with the given properties. Feature names that ImageIO plugins are expected to recognize include: 

"tiles"          Is this format able to write tiled images?
"rectangles"     Does this plugin accept arbitrary rectangular
                   pixel regions, not necessarily aligned to
                   scanlines or tiles?
"random_access"  May tiles or scanlines be written in
                   any order (false indicates that they MUST
                   be in successive order).
"multiimage"     Does this format support multiple subimages
                   within a file?
"appendsubimage" Does this format support adding subimages one at
                   a time through open(name,spec,AppendSubimage)?
                   If not, then open(name,subimages,specs) must
                   be used instead.
"mipmap"         Does this format support multiple resolutions
                   for an image/subimage?
"volumes"        Does this format support "3D" pixel arrays?
"rewrite"        May the same scanline or tile be sent more than
                   once?  (Generally, this will be true for
                   plugins that implement interactive display.)
"empty"          Does this plugin support passing a NULL data
                   pointer to write_scanline or write_tile to
                   indicate that the entire data block is zero?
"channelformats" Does the plugin/format support per-channel
                   data formats?
"displaywindow"  Does the format support display ("full") windows
                    distinct from the pixel data window?
"origin"         Does the format support a nonzero x,y,z
                    origin of the pixel data window?
"negativeorigin" Does the format support negative x,y,z
                    and full_{x,y,z} origin values?
"deepdata"       Deep (multi-sample per pixel) data

Note that main advantage of this approach, versus having separate individual supports_foo() methods, is that this allows future expansion of the set of possible queries without changing the API, adding new entry points, or breaking linkage compatibility.

type ImageSpec 

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

ImageSpec describes the data format of an image - dimensions, layout, number and meanings of image channels.

func NewImageSpec 

func NewImageSpec(format TypeDesc) *ImageSpec

given just the data format, set the default quantize and set all other channels to something reasonable.

func NewImageSpecSize 

func NewImageSpecSize(x, y, chans int, format TypeDesc) *ImageSpec

for simple 2D scanline image with nothing special. If fmt is not supplied, default to unsigned 8-bit data.

func (*ImageSpec) AlphaChannel 

func (s *ImageSpec) AlphaChannel() int

Index of alpha channel, or -1 if not known.

func (*ImageSpec) AttributeFloat 

func (s *ImageSpec) AttributeFloat(name string, defaultVal ...float32) float32

AttributeFloat looks up an existing attrib by name and returns the float value, or a default value if it does not exist. Default value is 0, if not specified.

func (*ImageSpec) AttributeInt 

func (s *ImageSpec) AttributeInt(name string, defaultVal ...int) int

AttributeInt looks up an existing attrib by name and returns the int value, or a default value if it does not exist. Default value is 0, if not specified.

func (*ImageSpec) AttributeString 

func (s *ImageSpec) AttributeString(name string, defaultVal ...string) string

AttributeString looks up an existing attrib by name and returns the string value, or a default value if it does not exist. Default value is an empty string, if not specified.

func (*ImageSpec) ChannelBytes 

func (s *ImageSpec) ChannelBytes() int

Return the number of bytes for each channel datum, assuming they are all stored using the data format given by format.

func (*ImageSpec) ChannelBytesChan 

func (s *ImageSpec) ChannelBytesChan(chanNum int, native bool) int

Return the number of bytes needed for the single specified channel. If native is false (default), compute the size of one channel of format, but if native is true, compute the size of the channel in terms of the "native" data format of that channel as stored in the file.

func (*ImageSpec) ChannelFormat 

func (s *ImageSpec) ChannelFormat(chanNum int) TypeDesc

func (*ImageSpec) ChannelFormats 

func (s *ImageSpec) ChannelFormats() []TypeDesc

Optional per-channel formats.

func (*ImageSpec) ChannelNames 

func (s *ImageSpec) ChannelNames() []string

String name of each channel

func (*ImageSpec) Deep 

func (s *ImageSpec) Deep() bool

Contains deep data.

func (*ImageSpec) DefaultChannelNames 

func (s *ImageSpec) DefaultChannelNames()

Set the channelnames to reasonable defaults ("R", "G", "B", "A"), and alpha_channel, based on the number of channels.

func (*ImageSpec) Depth 

func (s *ImageSpec) Depth() int

depth of pixel data, >1 indicates a "volume"

func (*ImageSpec) Destroy added in v1.1.0 

func (s *ImageSpec) Destroy()

Destroy the object immediately instead of waiting for GC.

func (*ImageSpec) EraseAttribute 

func (s *ImageSpec) EraseAttribute(name string, caseSensitive bool)

EraseAttribute removes the specified attribute from the list of extra_attribs. If not found, do nothing. If caseSensitive is true, the name search will be case-sensitive, otherwise the name search will be performed without regard to case

func (*ImageSpec) EraseAttributeType 

func (s *ImageSpec) EraseAttributeType(name string, searchType TypeDesc, caseSensitive bool)

EraseAttributeType removes the specified attribute from the list of extra_attribs. If not found, do nothing. If searchtype is anything but TypeUnknown, restrict matches to only those of the given type. If caseSensitive is true, the name search will be case-sensitive, otherwise the name search will be performed without regard to case

func (*ImageSpec) Format 

func (s *ImageSpec) Format() TypeDesc

data format of the channels

func (*ImageSpec) FullDepth 

func (s *ImageSpec) FullDepth() int

depth of the full (display) window

func (*ImageSpec) FullHeight 

func (s *ImageSpec) FullHeight() int

height of the full (display) window

func (*ImageSpec) FullWidth 

func (s *ImageSpec) FullWidth() int

width of the full (display) window

func (*ImageSpec) FullX 

func (s *ImageSpec) FullX() int

origin of the full (display) window

func (*ImageSpec) FullY 

func (s *ImageSpec) FullY() int

origin of the full (display) window

func (*ImageSpec) FullZ 

func (s *ImageSpec) FullZ() int

origin of the full (display) window

func (*ImageSpec) Height 

func (s *ImageSpec) Height() int

height of the pixel data window

func (*ImageSpec) ImageBytes 

func (s *ImageSpec) ImageBytes(native bool) int

Return the number of bytes for an entire image. This will return a max value in the event of an overflow where it's not representable in an int. If native is false, assume all channels are in format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats).

func (*ImageSpec) ImagePixels 

func (s *ImageSpec) ImagePixels() int

Return the number of pixels for an entire image. This will return a max value in the event of an overflow where it's not representable in an int.

func (*ImageSpec) NumChannels 

func (s *ImageSpec) NumChannels() int

number of image channels, e.g., 4 for RGBA

func (*ImageSpec) PixelBytes 

func (s *ImageSpec) PixelBytes(native bool) int

Return the number of bytes for each pixel (counting all channels). If native is false, assume all channels are in format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats). This will return a max value in the event of an overflow where it's not representable in a int.

func (*ImageSpec) PixelBytesChans 

func (s *ImageSpec) PixelBytesChans(chanBegin, chanEnd int, native bool) int

Return the number of bytes for just the subset of channels in each pixel described by [chanBegin, chanEnd). If native is false, assume all channels are in format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats). This will return a max value in the event of an overflow where it's not representable in a int.

func (*ImageSpec) ScanlineBytes 

func (s *ImageSpec) ScanlineBytes(native bool) int

Return the number of bytes for each scanline. This will return a max value in the event of an overflow where it's not representable in an int. If native is false, assume all channels are in format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats).

func (*ImageSpec) SetAlphaChannel 

func (s *ImageSpec) SetAlphaChannel(val int)

func (*ImageSpec) SetAttribute 

func (s *ImageSpec) SetAttribute(name string, val interface{}) error

SetAttribute sets a metadata value in the extra attribs. Acceptable types are string, int, and float32.

Example: 

s = NewImageSpec(...)
s.SetAttribute("foo_str", "blah")
s.SetAttribute("foo_int", 14)
s.SetAttribute("foo_float", 3.14)

func (*ImageSpec) SetChannelFormats 

func (s *ImageSpec) SetChannelFormats(formats []TypeDesc)

func (*ImageSpec) SetChannelNames 

func (s *ImageSpec) SetChannelNames(names []string)

SetChannelNames re-labels each existing channel, from a slice of string names.

func (*ImageSpec) SetDeep 

func (s *ImageSpec) SetDeep(val bool)

func (*ImageSpec) SetDepth 

func (s *ImageSpec) SetDepth(val int)

func (*ImageSpec) SetFormat 

func (s *ImageSpec) SetFormat(format TypeDesc)

Set the data format, and as a side effect set quantize to good defaults for that format

func (*ImageSpec) SetFullDepth 

func (s *ImageSpec) SetFullDepth(val int)

func (*ImageSpec) SetFullHeight 

func (s *ImageSpec) SetFullHeight(val int)

func (*ImageSpec) SetFullWidth 

func (s *ImageSpec) SetFullWidth(val int)

func (*ImageSpec) SetFullX 

func (s *ImageSpec) SetFullX(val int)

func (*ImageSpec) SetFullY 

func (s *ImageSpec) SetFullY(val int)

func (*ImageSpec) SetFullZ 

func (s *ImageSpec) SetFullZ(val int)

func (*ImageSpec) SetHeight 

func (s *ImageSpec) SetHeight(val int)

func (*ImageSpec) SetNumChannels 

func (s *ImageSpec) SetNumChannels(val int)

func (*ImageSpec) SetTileDepth 

func (s *ImageSpec) SetTileDepth(val int)

func (*ImageSpec) SetTileHeight 

func (s *ImageSpec) SetTileHeight(val int)

func (*ImageSpec) SetTileWidth 

func (s *ImageSpec) SetTileWidth(val int)

func (*ImageSpec) SetWidth 

func (s *ImageSpec) SetWidth(val int)

func (*ImageSpec) SetX 

func (s *ImageSpec) SetX(val int)

func (*ImageSpec) SetY 

func (s *ImageSpec) SetY(val int)

func (*ImageSpec) SetZ 

func (s *ImageSpec) SetZ(val int)

func (*ImageSpec) SetZChannel 

func (s *ImageSpec) SetZChannel(val int)

Set the index of the depth channel.

func (*ImageSpec) SizeSafe 

func (s *ImageSpec) SizeSafe() bool

Verify that on this platform, a size_t is big enough to hold the number of bytes (and pixels) in a scanline, a tile, and the whole image. If this returns false, the image is much too big to allocate and read all at once, so client apps beware and check these routines for overflows!

func (*ImageSpec) TileBytes 

func (s *ImageSpec) TileBytes(native bool) int

Return the number of bytes for each a tile of the image. This will return a max value in the event of an overflow where it's not representable in an imagesize_t. If native is false, assume all channels are in format, but if native is true, compute the size of a pixel in the "native" data format of the file (these may differ in the case of per-channel formats).

func (*ImageSpec) TileDepth 

func (s *ImageSpec) TileDepth() int

func (*ImageSpec) TileHeight 

func (s *ImageSpec) TileHeight() int

tile height (0 for a non-tiled image)

func (*ImageSpec) TilePixels 

func (s *ImageSpec) TilePixels() int

Return the number of pixels for a tile. This will return a max value in the event of an overflow where it's not representable in an int.

func (*ImageSpec) TileWidth 

func (s *ImageSpec) TileWidth() int

tile width (0 for a non-tiled image)

func (*ImageSpec) ToXml 

func (s *ImageSpec) ToXml() string

Convert ImageSpec class into XML string.

func (*ImageSpec) Width 

func (s *ImageSpec) Width() int

width of the pixel data window

func (*ImageSpec) X 

func (s *ImageSpec) X() int

Properties

func (*ImageSpec) Y 

func (s *ImageSpec) Y() int

func (*ImageSpec) Z 

func (s *ImageSpec) Z() int

origin (upper left corner) of pixel data

func (*ImageSpec) ZChannel 

func (s *ImageSpec) ZChannel() int

Index of depth channel, or -1 if not known.

type ProgressCallback 

type ProgressCallback func(done float32) bool

For image processing functions that accept a callback to monitor progress. A function that will be passed a float value indicating the progress percentage of the current operation. If the functon returns true, then the process should be aborted. Return false to allow processing to continue.

type ROI 

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

Helper struct describing a region of interest in an image. The region is [xbegin,xend) x [begin,yend) x [zbegin,zend), with the "end" designators signifying one past the last pixel, a la C++ STL style.

func NewROI 

func NewROI() *ROI

Default constructor is an undefined region.

func NewROIRegion2D 

func NewROIRegion2D(xbegin, xend, ybegin, yend int) *ROI

Constructor with an explicitly defined region, where you are concerned with just the X/Y region, and not the Z or the channels

func NewROIRegion3D 

func NewROIRegion3D(xbegin, xend, ybegin, yend, zbegin, zend, chbegin, chend int) *ROI

Constructor with an explicitly defined region. Reasonable default values are: 

zbegin  = 0
zend    = 1
chbegin = 0
chend   = 1000

func (*ROI) ChannelsBegin 

func (r *ROI) ChannelsBegin() int

func (*ROI) ChannelsEnd 

func (r *ROI) ChannelsEnd() int

func (*ROI) Copy 

func (r *ROI) Copy() *ROI

Return a new copy of the ROI that can be freely modified.

func (*ROI) Defined 

func (r *ROI) Defined() bool

Is a region defined?

func (*ROI) Depth 

func (r *ROI) Depth() int

Depth of the region (Z)

func (*ROI) Destroy added in v1.1.0 

func (r *ROI) Destroy()

Destroy the object immediately instead of waiting for GC.

func (*ROI) Height 

func (r *ROI) Height() int

Height of the region (Y)

func (*ROI) NumChannels 

func (r *ROI) NumChannels() int

Number of channels in the region

func (*ROI) NumPixels 

func (r *ROI) NumPixels() int

Number of total pixels in the region This is Width * Height * Depth

func (*ROI) SetChannelsBegin 

func (r *ROI) SetChannelsBegin(ch int)

func (*ROI) SetChannelsEnd 

func (r *ROI) SetChannelsEnd(ch int)

func (*ROI) SetXBegin 

func (r *ROI) SetXBegin(x int)

func (*ROI) SetXEnd 

func (r *ROI) SetXEnd(x int)

func (*ROI) SetYBegin 

func (r *ROI) SetYBegin(y int)

func (*ROI) SetYEnd 

func (r *ROI) SetYEnd(y int)

func (*ROI) SetZBegin 

func (r *ROI) SetZBegin(z int)

func (*ROI) SetZEnd 

func (r *ROI) SetZEnd(z int)

func (*ROI) String 

func (r *ROI) String() string

String returns a printable string representation of the ROI, containing just the origin (X,Y) and Width,Height.

func (*ROI) Width 

func (r *ROI) Width() int

Width of the region (X)

func (*ROI) XBegin 

func (r *ROI) XBegin() int

func (*ROI) XEnd 

func (r *ROI) XEnd() int

func (*ROI) YBegin 

func (r *ROI) YBegin() int

func (*ROI) YEnd 

func (r *ROI) YEnd() int

func (*ROI) ZBegin 

func (r *ROI) ZBegin() int

func (*ROI) ZEnd 

func (r *ROI) ZEnd() int

type TypeDesc 

type TypeDesc int

Various representation formats for image data 

const (
	TypeUnknown TypeDesc = C.TYPE_UNKNOWN
	TypeUint8   TypeDesc = C.TYPE_UINT8
	TypeInt8    TypeDesc = C.TYPE_INT8
	TypeUint16  TypeDesc = C.TYPE_UINT16
	TypeInt16   TypeDesc = C.TYPE_INT16
	TypeUint    TypeDesc = C.TYPE_UINT
	TypeInt     TypeDesc = C.TYPE_INT
	TypeUint64  TypeDesc = C.TYPE_UINT64
	TypeInt64   TypeDesc = C.TYPE_INT64
	TypeHalf    TypeDesc = C.TYPE_HALF
	TypeFloat   TypeDesc = C.TYPE_FLOAT
	TypeDouble  TypeDesc = C.TYPE_DOUBLE
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.