superimage

README

SuperImage

The package provides some useful structures and functions for working with images. Apply effects such as blur or negative color to an image with a well-performing tool.

Index

• SuperImage
  • Index
  • Getting Started
    • Installation
    • Quick start
  • Examples
  • References
    • About SuperImage
    • Using GetByURL
    • Using GetByFile
    • Using Decode
    • Using Encode
    • Using ParseURL
    • Using Negative
    • Using Flip
    • Using Reflect
    • Using Blur
  • Interest links

Getting Started

Installation

To install SuperImage package, you need solve the following issues:

1. Install Go (version 1.18.+ required).

2. Import it in your code:

    import "github.com/nicolito128/superimage"

1. Get the package using go modules:

    go get github.com/nicolito/superimage

Quick start

project/main.go:

package main

import (
    "bytes"
	"io/ioutil"

    "github.com/nicolito128/superimage"
)

func main() {
    img, err := superimage.GetByURL("https://go.dev/blog/gopher/gopher.png")
    if err != nil {
        panic(err)
    }

    // Buffer for store the image data
    buf := new(bytes.Buffer)
    // Encode writes the image into the buffer
    // gopher is ".png", so options can be nil
    err = superimage.Encode(buf, img, nil)
    if err != nil {
        panic(err)
    }

    // Writing the cute gopher
    ioutil.WriteFile("gopher.png", buf.Bytes(), 0666)
}

Examples

You have some good examples on how to use the package in the examples/ folder.

References

About SuperImage

SuperImage is an Go struct, it can be used as any Image from the std image package because it's an Image interface implementation with the methods At(), Bounds() and ColorModel(). You can create a new SuperImage with the New(...) function.

func main() {
    rec := image.Rectangle{image.Point{0, 0}, image.Point{500, 500}}
    boringImg := image.NewRGBA(rec)
    superImg := superimage.New(boringImg, "png")

    println(superImg.Bounds())
}

Using GetByURL

Get a new SuperImage with an URL.

func main() {
    // Getting a new SuperImage with a link
    urlImg, err := superimage.GetByURL("https://awesomeurl.com/image.png")
    if err != nil {
        panic(err)
    }

    println(urlImg.Width, urlImg.Height)
}

Using GetByFile

Get a new SuperImage with a project file image.

func main() {
    // Getting a new SuperImage with a file
    fileImg, err := superimage.GetByFile("./folder/cool_image.jpg")
    if err != nil {
        panic(err)
    }

    println(fileImg.Width, fileImg.Height)
}

Using Decode

Decodes an reader on a new SuperImage.

func main() {
    file, _ := os.Open("./examples/gopher/gopher.png")
	i, err := superimage.Decode(file, "png")
    if err != nil {
        panic(err)
    }

	println(i.Height, i.Width)
}

Using Encode

Encodes a writer on a new SuperImage.

func main() {
    fileImg, err := superimage.GetByFile("./folder/cool_image.jpg")
    if err != nil {
        panic(err)
    }

    buf := new(bytes.Buffer)
	err = superimage.Encode(buf, img, nil)
	if err != nil {
		panic(err)
	}

    println(len(buf.Bytes()))
}

Using ParseURL

func main() {
    url, format, err := superimage.ParseURL("./project/images/cool.jpg")
    if err != nil {
        panic(err)
    }

    println(url.Path, format)
}

Using Negative

Inverts the colors of an image.

func main() {
    img, err := superimage.GetByURL("https://awesomeurl.com/image.png")
    if err != nil {
        panic(err)
    }

    // Inverting image colors
    neg := superimage.Negative(img)

    // Saving
    buf := new(bytes.Buffer)
    err = superimage.Encode(buf, neg, nil)
    if err != nil {
        panic(err)
    }

    ioutil.WriteFile("./negative.png", buf.Bytes(), 0666)
}

Using Flip

Turn an image upside down.

func main() {
    img, err := superimage.GetByURL("https://awesomeurl.com/image.png")
    if err != nil {
        panic(err)
    }

    // Flipping image
    flipped := superimage.Flip(img)

    // Saving
    buf := new(bytes.Buffer)
    err = superimage.Encode(buf, flipped, nil)
    if err != nil {
        panic(err)
    }

    ioutil.WriteFile("./flipped.png", buf.Bytes(), 0666)
}

Using Reflect

Reflects an image vertically.

func main() {
    img, err := superimage.GetByURL("https://awesomeurl.com/image.png")
    if err != nil {
        panic(err)
    }

    // Reflecting image
    reflect := superimage.Reflect(img)

    // Saving
    buf := new(bytes.Buffer)
    err = superimage.Encode(buf, reflect, nil)
    if err != nil {
        panic(err)
    }

    ioutil.WriteFile("./reflect.png", buf.Bytes(), 0666)
}

Using Blur

Blur an image by a given radio.

func main() {
    img, err := superimage.GetByURL("https://awesomeurl.com/image.png")
    if err != nil {
        panic(err)
    }

    // Blur
    blurred, err := superimage.Blur(img, 2)
    if err != nil {
        panic(err)
    }

    // Saving
    buf := new(bytes.Buffer)
    err = superimage.Encode(buf, blurred, nil)
    if err != nil {
        panic(err)
    }

    ioutil.WriteFile("./blurred.png", buf.Bytes(), 0666)
}

Interest links

• Go image standard library

Documentation

Index

• Variables
• func Encode(w io.Writer, m *SuperImage, op *EncodeOptions) error
• func ParseURL(link string) (u *url.URL, format string, err error)
• type EncodeOptions
• type FactoryOptions
• type SuperImage
  • func Blur(img *SuperImage, radio int) (*SuperImage, error)
  • func Decode(r io.Reader, format string) (*SuperImage, error)
  • func Flip(img *SuperImage) *SuperImage
  • func GetByFile(filename string) (*SuperImage, error)
  • func GetByURL(link string) (*SuperImage, error)
  • func Negative(img *SuperImage) *SuperImage
  • func New(im image.Image, format string) *SuperImage
  • func Opacity(img *SuperImage, op float64) (*SuperImage, error)
  • func Reflect(img *SuperImage) *SuperImage
  • func (s *SuperImage) At(x, y int) color.Color
  • func (s *SuperImage) Bounds() image.Rectangle
  • func (s *SuperImage) ColorModel() color.Model
  • func (s *SuperImage) Factory(model image.Image, op *FactoryOptions) image.Image

Variables

var ErrInvalidOpacity = errors.New("Opacity must be between 0 and 1.")

var ErrNegativeRadio = errors.New("Radio must be higher than 0.")

Functions

func Encode

func Encode(w io.Writer, m *SuperImage, op *EncodeOptions) error

Encode writes the Image m to the given writer in the specified format (png, jpg, jpeg). If op *EncodeOptions is nil, the default options used are: { Quality: 100 }.

func ParseURL

func ParseURL(link string) (u *url.URL, format string, err error)

ParseURL parses an URL.

Types

type EncodeOptions

type EncodeOptions struct {
	// Encode quality for Jpeg format: 1-100
	Quality int
}

type FactoryOptions

type FactoryOptions struct {
	YCbCrSubsampleRatio image.YCbCrSubsampleRatio
	Palette             *color.Palette
	Uniform             *color.Color
}

type SuperImage

type SuperImage struct {

	// Sizes of the image.
	Width  int
	Height int
	// Image format: png, jpg, jpeg.
	Format string
	// contains filtered or unexported fields
}

SuperImage is an image.Image implementation that wraps another image.Image.

func Blur

func Blur(img *SuperImage, radio int) (*SuperImage, error)

Blur blurs an image by a given radio. If the radio is negative or bigger than the image's width or height, it returns an error. Radio 0 returns the original image without any change.

References: https://relate.cs.illinois.edu/course/cs357-f15/file-version/03473f64afb954c74c02e8988f518de3eddf49a4/media/00-python-numpy/Image%20Blurring.html | http://arantxa.ii.uam.es/~jms/pfcsteleco/lecturas/20081215IreneBlasco.pdf

func Decode

func Decode(r io.Reader, format string) (*SuperImage, error)

Decode decodes an image from r using the specified format (png, jpg, jpeg).

func Flip

func Flip(img *SuperImage) *SuperImage

Flip inverts the image horizontally returning a new *SuperImage.

func GetByFile

func GetByFile(filename string) (*SuperImage, error)

GetImageFile gets an image from a current project file.

func GetByURL

func GetByURL(link string) (*SuperImage, error)

GetImageFromURL gets an image from an URL with an http GET request.

func Negative

func Negative(img *SuperImage) *SuperImage

Negative inverts the colors of an image.

func New

func New(im image.Image, format string) *SuperImage

func Opacity

func Opacity(img *SuperImage, op float64) (*SuperImage, error)

func Reflect

func Reflect(img *SuperImage) *SuperImage

Reflect inverts the image vertically returning a new *SuperImage.

func (*SuperImage) At

func (s *SuperImage) At(x, y int) color.Color

At returns the color of the pixel at (x, y). At(Bounds().Min.X, Bounds().Min.Y) returns the upper-left pixel of the grid. At(Bounds().Max.X-1, Bounds().Max.Y-1) returns the lower-right one.

func (*SuperImage) Bounds

func (s *SuperImage) Bounds() image.Rectangle

Bounds returns the domain for which At can return non-zero color. The bounds do not necessarily contain the point (0, 0).

func (*SuperImage) ColorModel

func (s *SuperImage) ColorModel() color.Model

ColorModel returns the Image's color model.

func (*SuperImage) Factory

func (s *SuperImage) Factory(model image.Image, op *FactoryOptions) image.Image

Factory creates a new image of the same type as the model passed as argument. The function receives a FactoryOptions struct as argument, it can be nil. Also, any field of the struct can be nil, if the field is nil the function sets an default value.

The FactoryOptions has the following fields by default:

{ YCbCrSubsampleRatio: 4, Palette: new(color.Pallete), Uniform: new(color.Color) }