icns

README

icns

Easily convert .jpg and .png to .icns with the command line tool icnsify, or use the library to convert from any image.Image to .icns.

go get github.com/jackmordaunt/icns

icns files allow for high resolution icons to make your apps look sexy. The most common ways to generate icns files are:

1. iconutil, which is a Mac native cli utility.
2. ImageMagick which adds a large dependency to your project for such a simple use case.

With this library you can use pure Go to create icns files from any source image, given that you can decode it into an image.Image, without any heavyweight dependencies or subprocessing required. You can also use it to create icns files on windows and linux (thanks Go).

A small CLI app icnsify is provided allowing you to create icns files using this library from the command line. It supports piping, which is something iconutil does not do, making it substantially easier to wrap or chuck into a shell pipeline.

Note: All icons within the icns are sized for high dpi retina screens, using the appropriate icns OSTypes.

GUI

preview is a gui for displaying icns files cross-platform.

Go Tool

go install github.com/jackmordaunt/icns/cmd/preview@latest

Clone

git clone https://github.com/jackmordaunt/icns
cd icns/cmd/preview && go install .

Note: Gio cannot be cross-compiled right now, so there are no preview builds in releases. Note: preview has it's own go.mod and therefore is versioned independently (unversioned).

Command Line

Go Tool

go install github.com/jackmordaunt/icns/v2/cmd/icnsify@latest

Scoop

scoop bucket add extras # Ensure bucket is added first
scoop install icnsify

Or from my personal bucket:

scoop bucket add jackmordaunt https://github.com/jackmordaunt/scoop-bucket 
scoop install jackmordaunt/icns # Name is defaulted to repo name. 

Winget

winget install icnsify

Brew

brew tap jackmordaunt/homebrew-tap # Ensure tap is added first.
brew install icnsify

Clone

git clone https://github.com/jackmordaunt/icns
cd icns && go install ./cmd/icnsify

Pipe it

cat icon.png | icnsify > icon.icns

cat icon.icns | icnsify > icon.png

Standard

icnsify -i icon.png -o icon.icns

icnsify -i icon.icns -o icon.png

Library

go get github.com/jackmordaunt/icns/v2

func main() {
        pngf, err := os.Open("path/to/icon.png")
        if err != nil {
                log.Fatalf("opening source image: %v", err)
        }
        defer pngf.Close()
        srcImg, _, err := image.Decode(pngf)
        if err != nil {
                log.Fatalf("decoding source image: %v", err)
        }
        dest, err := os.Create("path/to/icon.icns")
        if err != nil {
                log.Fatalf("opening destination file: %v", err)
        }
        defer dest.Close()
        if err := icns.Encode(dest, srcImg); err != nil {
                log.Fatalf("encoding icns: %v", err)
        }
}

Roadmap

• Encoder: image.Image -> .icns
• Command Line Interface
  • Encoding
  • Pipe support
  • Decoding
• Implement Decoder: .icns -> image.Image
• Symmetric test: decode(encode(img)) == img

Coffee

If this software is useful to you, consider buying me a coffee!

https://liberapay.com/JackMordaunt

Documentation

Overview

Package icns implements an encoder for Apple's `.icns` file format. Reference: "https://en.wikipedia.org/wiki/Apple_Icon_Image_format".

icns files allow for high resolution icons to make your apps look sexy. The most common ways to generate icns files are 1. use `iconutil` which is a Mac native cli utility, or 2. use tools that wrap `ImageMagick` which adds a large dependency to your project for such a simple use case.

With this library you can use pure Go to create icns files from any source image, given that you can decode it into an `image.Image`, without any heavyweight dependencies or subprocessing required. You can also use this library to create icns files on windows and linux.

A small CLI app `icnsify` is provided to allow you to create icns files using this library from the command line. It supports piping, which is something `iconutil` does not do, making it substantially easier to wrap.

Note: All icons within the icns are sized for high dpi retina screens, using the appropriate icns OSTypes.

Index

• func Decode(r io.Reader) (image.Image, error)
• func DecodeAll(r io.Reader) (images []image.Image, err error)
• func Encode(wr io.Writer, img image.Image) error
• type Encoder
  • func NewEncoder(wr io.Writer) *Encoder
  • func (enc *Encoder) Encode(img image.Image) error
  • func (enc *Encoder) WithAlgorithm(a InterpolationFunction) *Encoder
• type ErrImageTooSmall
  • func (err ErrImageTooSmall) Error() string
• type Icon
  • func (i *Icon) WriteTo(wr io.Writer) (int64, error)
• type IconSet
  • func NewIconSet(img image.Image, interp InterpolationFunction) (*IconSet, error)
  • func (s *IconSet) WriteTo(wr io.Writer) (int64, error)
• type InterpolationFunction
• type OsType

Functions

func Decode

func Decode(r io.Reader) (image.Image, error)

Decode finds the largest icon listed in the icns file and returns it, ignoring all other sizes. The format returned will be whatever the icon data is, typically jpeg or png.

func DecodeAll

func DecodeAll(r io.Reader) (images []image.Image, err error)

DecodeAll extracts all icon resolutions present in the icns data.

func Encode

func Encode(wr io.Writer, img image.Image) error

Encode writes img to wr in ICNS format. img is assumed to be a rectangle; non-square dimensions will be squared without preserving the aspect ratio. Uses nearest neighbor as interpolation algorithm.

Types

type Encoder

type Encoder struct {
	Wr        io.Writer
	Algorithm InterpolationFunction
}

Encoder encodes ICNS files from a source image.

func NewEncoder

func NewEncoder(wr io.Writer) *Encoder

NewEncoder initialises an encoder.

func (*Encoder) Encode

func (enc *Encoder) Encode(img image.Image) error

Encode icns with the given configuration.

func (*Encoder) WithAlgorithm

func (enc *Encoder) WithAlgorithm(a InterpolationFunction) *Encoder

WithAlgorithm applies the interpolation function used to resize the image.

type ErrImageTooSmall

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

ErrImageTooSmall is returned when the image is too small to process.

func (ErrImageTooSmall) Error

func (err ErrImageTooSmall) Error() string

type Icon

type Icon struct {
	Type  OsType
	Image image.Image
	// contains filtered or unexported fields
}

Icon encodes an icns icon.

func (*Icon) WriteTo

func (i *Icon) WriteTo(wr io.Writer) (int64, error)

WriteTo encodes the icon into wr.

type IconSet

type IconSet struct {
	Icons []*Icon
	// contains filtered or unexported fields
}

IconSet encodes a set of icons into an ICNS file.

func NewIconSet

func NewIconSet(img image.Image, interp InterpolationFunction) (*IconSet, error)

NewIconSet uses the source image to create an IconSet. If width != height, the image will be resized using the largest side without preserving the aspect ratio.

func (*IconSet) WriteTo

func (s *IconSet) WriteTo(wr io.Writer) (int64, error)

WriteTo writes the ICNS file to wr.

type InterpolationFunction

type InterpolationFunction = resize.InterpolationFunction

InterpolationFunction is the algorithm used to resize the image.

const (
	// Nearest-neighbor interpolation
	NearestNeighbor InterpolationFunction = iota
	// Bilinear interpolation
	Bilinear
	// Bicubic interpolation (with cubic hermite spline)
	Bicubic
	// Mitchell-Netravali interpolation
	MitchellNetravali
	// Lanczos interpolation (a=2)
	Lanczos2
	// Lanczos interpolation (a=3)
	Lanczos3
)

InterpolationFunction constants.

type OsType

type OsType struct {
	ID   string
	Size uint
}

OsType is a 4 character identifier used to differentiate icon types.