picturebook

package module
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Jan 30, 2024 License: BSD-3-Clause Imports: 23 Imported by: 1

README

go-picturebook

Create a PDF file (a "picturebook") from a folder (containing images).

Documentation

Go Reference

Tools

To build binary versions of these tools run the cli Makefile target. For example:

$> make cli
go build -mod vendor -o bin/picturebook cmd/picturebook/main.go
picturebook

Create a PDF file (a "picturebook") from a folder (containing images).

$> ./bin/picturebook -h
  -bleed float
    	An additional bleed area to add (on all four sides) to the size of your picturebook.
  -border float
    	The size of the border around images. (default 0.01)
  -caption value
    	Zero or more valid caption.Caption URIs. Valid schemes are: exif://, filename://, json://, modtime://, multi://, none://.
  -dpi float
    	The DPI (dots per inch) resolution for your picturebook. (default 150)
  -even-only
    	Only include images on even-numbered pages.
  -filename string
    	The filename (path) for your picturebook. (default "picturebook.pdf")
  -fill-page
    	If necessary rotate image 90 degrees to use the most available page space. Note that any '-process' flags involving colour space manipulation will automatically be applied to images after they have been rotated.
  -filter value
    	A valid filter.Filter URI. Valid schemes are: any://, regexp://.
  -height float
    	A custom width to use as the size of your picturebook. Units are defined in inches by default. This flag overrides the -size flag when used in combination with the -width flag.
  -margin float
    	The margin around all sides of a page. If non-zero this value will be used to populate all the other -margin-(N) flags.
  -margin-bottom float
    	The margin around the bottom of each page. (default 1)
  -margin-left float
    	The margin around the left-hand side of each page. (default 1)
  -margin-right float
    	The margin around the right-hand side of each page. (default 1)
  -margin-top float
    	The margin around the top of each page. (default 1)
  -max-pages int
    	An optional value to indicate that a picturebook should not exceed this number of pages
  -ocra-font
    	Use an OCR-compatible font for captions.
  -odd-only
    	Only include images on odd-numbered pages.
  -orientation string
    	The orientation of your picturebook. Valid orientations are: 'P' and 'L' for portrait and landscape mode respectively. (default "P")
  -process value
    	A valid process.Process URI. Valid schemes are: colorspace://, colourspace://, contour://, halftone://, null://, rotate://.
  -size string
    	A common paper size to use for the size of your picturebook. Valid sizes are: "a3", "a4", "a5", "letter", "legal", or "tabloid". (default "letter")
  -sort string
    	A valid sort.Sorter URI. Valid schemes are: exif://, modtime://.
  -source-uri string
    	A valid GoCloud blob URI to specify where files should be read from. Available schemes are: file://. If no URI scheme is included then the file:// scheme is assumed.
  -target-uri string
    	A valid GoCloud blob URI to specify where files should be read from. Available schemes are: file://. If no URI scheme is included then the file:// scheme is assumed. If empty then the code will try to use the operating system's 'current working directory' where applicable.
  -text string
    	A valid text.Text URI. Valid schemes are: json://.
  -tmpfile-uri string
    	A valid GoCloud blob URI to specify where files should be read from. Available schemes are: file://. If no URI scheme is included then the file:// scheme is assumed. If empty the operating system's temporary directory will be used.
  -units string
    	The unit of measurement to apply to the -height and -width flags. Valid options are inches, millimeters, centimeters (default "inches")
  -verbose
    	Display verbose output as the picturebook is created.
  -width float
    	A custom height to use as the size of your picturebook. Units are defined in inches by default. This flag overrides the -size flag when used in combination with the -height flag.

For example:

$> ./bin/picturebook \
	-source-uri file:///PATH/TO/go-picturebook/example \
	-target-uri file:///PATH/TO/go-picturebook/example \
	images

As a convenience if no paths (to folders containing images) are passed to the picturebook tool it will be assumed that images are found in the folder defined by the -source-uri flag. For example this command is functionally equivalent to the command above:

$> ./bin/picturebook \
	-source-uri file:///PATH/TO/go-picturebook/example/images \
	-target-uri file:///PATH/TO/go-picturebook/example \

For a complete example, including a PDF file produced by the picturebook tool, have a look in the example folder.

Source and target URIs

Under the hood picturebook is using the Go Cloud blob abstraction layer for files and file storage. By default only local files (or file:// URIs) are supported. If you need to support other sources or targets you will need to create your own custom picturebook tool.

In order to facilitate this all of the logic of the picturebook tool has been moved in to the go-picturebook/application/commandline package. For example here is how you would write your own custom tool with support for reading and writing files to an S3 bucket as well as the local filesystem.

package main

import (
	"context"
	"github.com/aaronland/go-picturebook/application/commandline"
	_ "gocloud.dev/blob/fileblob"
	_ "gocloud.dev/blob/s3blob"	
)

func main() {

	ctx := context.Background()

	fs, _ := commandline.DefaultFlagSet(ctx)
	app, _ := commandline.NewApplication(ctx, fs)

	app.Run(ctx)
}

Error handling has been omitted for the sake of brevity.

Handlers

The picturebook application supports a number of "handlers" for customizing which images are included, how and whether they are transformed before inclusion and how to derive that image's caption.

Captions
type Caption interface {
	Text(context.Context, *blob.Bucket, string) (string, error)
}

For an example of how to create and register a custom Caption handler take a look at the code in caption/filename.go.

The following schemes for caption handlers are supported by default:

exif://?property={PROPERTY}

The handler will eventually return the value of a given EXIF property. As of this writing it will only return the value of the EXIF DateTime property.

If EXIF data is not present or can be loaded the handler will return an empty string.

Parameters

Name Value Required
property "datetime" yes
filename://

This handler will return the filename for a given path of an image.

json://{PATH/TO/CAPTIONS.json}

This handler will assign captions derived from a JSON file that can be read from the local disk. The JSON file is expected to be a dictionary whose keys are the filenames of the images being included in the picturebook and whose values are a list of strings to use as caption text.

modtime://

This handler will assign captions derived from an image's modification time.

none://

The handler will return an empty string for all images.

Filters
type Filter interface {
	Continue(context.Context, *blob.Bucket, string) (bool, error)
}

For an example of how to create and register a custom Filter handler take a look at the code in filter/regexp.go.

The following schemes for filter handlers are supported by default:

any://

Allow all images to be included.

regexp://exclude

This handler will exclude any images whose path matches the specified regular expression.

Parameters

Name Value Required
pattern A valid Go language regular expresssion yes
regexp://include

This handler will include only those images whose path matches the specified regular expression.

Parameters

Name Value Required
pattern A valid Go language regular expresssion yes
Processes
type Process interface {
	Transform(context.Context, *blob.Bucket, string) (string, error)
}

For an example of how to create and register a custom Process handler take a look at the code in process/halftone.go.

The following schemes for process handlers are supported by default:

colourspace://

This handler will map all the pixels in an image to a given colour space (Apple's Display P3, Adobe RGB) before including it in your picturebook. URIs should take the form of `colourspace://{{LABEL}.

Labels
Name Description
adobergb Convert all pixels in to the Adobe RGB colour space
displayp3 Convert all pixels in to Apple's Display P3 colour space
colorspace://

This handler will map all the pixels in an image to a given colour space (Apple's Display P3, Adobe RGB) before including it in your picturebook. URIs should take the form of `colorspace://{{LABEL}.

Labels
Name Description
adobergb Convert all pixels in to the Adobe RGB colour space
displayp3 Convert all pixels in to Apple's Display P3 colour space
contour://

This handler will convert an image into a series of black and white "contour" lines using the fogleman/contourmap package. URIs should take the form of contour://?{PARAMETERS}.

Parameters
Name Value Required Default
iterations The number of iterations to perform during the contour process no 12
scale The scale of the final contoured image no 1.0
halftone://

This handler will dither (halftone) an image before including it in your picturebook.

null://

This handler doesn't do anything to an image before including it in your picturebook.

rotate://

This handler will attempt to auto-rotate an image, based on any available EXIF Orientation data, before including it in your picturebook.

Sorters
type Sorter interface {
	Sort(context.Context, *blob.Bucket, []*picture.PictureBookPicture) ([]*picture.PictureBookPicture, error)
}

For an example of how to create and register a custom Sorter handler take a look at the code in sort/orthis.go.

The following schemes for sorter handlers are supported by default:

exif://

Sort images, in ascending order, by their EXIF DateTime property. If EXIF data is not present or can not be loaded the image's modification time will be used. If two or more images have the same modification they will sorted again by their file size.

modtime://

Sort images, in ascending order, by their modification times. If two or more images have the same modification they will sorted again by their file size.

See also

Documentation

Index

Constants

View Source 
const MM2INCH float64 = 25.4

MM2INCH defines the number if millimeters in an inch.

Variables

This section is empty.

Functions

This section is empty.

Types

type GatherPicturesProcessFunc added in v0.5.2 

type GatherPicturesProcessFunc func(context.Context, string) (*picture.PictureBookPicture, error)

type GatherPicturesProcessFunc defines a method for processing the path to an image file in to a `picture.PictureBookPicture` instance.

func DefaultGatherPicturesProcessFunc added in v0.5.2 

func DefaultGatherPicturesProcessFunc(pb_opts *PictureBookOptions) (GatherPicturesProcessFunc, error)
DefaultGatherPicturesProcessFunc returns a default GatherPicturesProcessFunc used to derive a `picture.PictureBookPicture` instance

from the path to an image file. It applies any filters and transformation processes and derives caption data per settings defined in 'pb_opts'.

type PictureBook 

type PictureBook struct {
	// A `fpdf.Fpdf` instance used to produce the picturebook PDF file.
	PDF *fpdf.Fpdf
	// A `sync.Mutex` instance used to add images in an orderly fashion.
	Mutex *sync.Mutex
	// The `PictureBookBorders` definition to use for this picturebook
	Borders *PictureBookBorders
	// The `PictureBookMargins` definition to use for this picturebook
	Margins *PictureBookMargins
	// The `PictureBookCanvas` definition to use for this picturebook
	Canvas PictureBookCanvas
	// The `PictureBookText` definition to use for this picturebook
	Text PictureBookText
	// The `PictureBookOptions` used to create this picturebook
	Options *PictureBookOptions
	// The `GatherPicturesProcessFunc` function used to determine whether an image is included in a picturebook
	ProcessFunc GatherPicturesProcessFunc
	// contains filtered or unexported fields
}

type PictureBook provides a struct for creating a PDF file from a folder of images (a picturebook).

func NewPictureBook 

func NewPictureBook(ctx context.Context, opts *PictureBookOptions) (*PictureBook, error)

NewPictureBook returns a new `PictureBook` instances configured according to the settings in 'opts'.

func (*PictureBook) AddBlankPage added in v0.4.7 

func (pb *PictureBook) AddBlankPage(ctx context.Context, pagenum int) error

AddBlankPage add a blank page the final PDF document at page 'pagenum'.

func (*PictureBook) AddPicture 

func (pb *PictureBook) AddPicture(ctx context.Context, pagenum int, pic *picture.PictureBookPicture) error

func (*PictureBook) AddPictures 

func (pb *PictureBook) AddPictures(ctx context.Context, paths []string) error

AddPictures adds images founds in one or more folders defined 'paths' to the picturebook instance.

func (*PictureBook) AddText added in v0.8.0 

func (pb *PictureBook) AddText(ctx context.Context, pagenum int, pic *picture.PictureBookPicture) error

AddText add the value of `pic.Text` on the adjacent page to `pic`.

func (*PictureBook) GatherPictures added in v0.2.0 

func (pb *PictureBook) GatherPictures(ctx context.Context, paths []string) ([]*picture.PictureBookPicture, error)

GatherPictures collects all the images in one or more folders defined by 'paths' and returns a list of `picture.PictureBookPicture` instances.

func (*PictureBook) Save 

func (pb *PictureBook) Save(ctx context.Context, path string) error

Save will write the picturebook to 'path' in the `Target` bucket specified in the `PictureBookOptions` used to create the picturebook option.

type PictureBookBorders added in v0.4.9 

type PictureBookBorders struct {
	// The size of any border to add to the top of each image.
	Top float64
	// The size of any border to add to the bottom of each image.
	Bottom float64
	// The size of any border to add to the left-hand side of each image.
	Left float64
	// The size of any border to add to the right-hand side of each image.
	Right float64
}

type PictureBookBorders defines a struct for storing borders to be applied to a images in a picturebook.

type PictureBookCanvas 

type PictureBookCanvas struct {
	// The width of the internal picturebook canvas.
	Width float64
	// The height of the internal picturebook canvas.
	Height float64
}

type PictureBookCanvas defines a struct for storing canvas information for a picturebook.

type PictureBookMargins added in v0.4.9 

type PictureBookMargins struct {
	// The size of any margin to add to the top of each page.
	Top float64
	// The size of any margin to add to the bottom of each page.
	Bottom float64
	// The size of any margin to add to the left-hand side of each page.
	Left float64
	// The size of any margin to add to the right-hand side of each page.
	Right float64
}

type PictureBookMargins defines a struct for storing margins to be applied to a picturebook

type PictureBookOptions 

type PictureBookOptions struct {
	// The orientation of the final picturebook. Valid options are "P" and "L" for portrait and landscape respectively.
	Orientation string
	// A string label corresponding to known size. Valid options are "a1", "a2", "a3", "a4", "a5", "a6", "a7", "letter", "legal" and "tabloid".
	Size string
	// The width of the final picturebook.
	Width float64
	// The height of the final picturebook.
	Height float64
	// The unit of measurement to use for the `Width` and `Height` options.
	Units string
	// The number dots per inch to use when calculating the size of the final picturebook. Valid options are "inches", "centimeters", "millimeters".
	DPI float64
	// The size of any border to apply to each image in the final picturebook.
	Border float64
	// The size of any additional bleed to apply to the final picturebook.
	Bleed float64
	// The size of any margin to add to the top of each page.
	MarginTop float64
	// The size of any margin to add to the bottom of each page.
	MarginBottom float64
	// The size of any margin to add to the left-hand side of each page.
	MarginLeft float64
	// The size of any margin to add to the right-hand side of each page.
	MarginRight float64
	// An optional `filter.Filter` instance used to determine whether or not an image should be included in the final picturebook.
	Filter filter.Filter
	// Zero or more optional `process.Process` instance used to transform images being included in the final picturebook.
	PreProcess process.Process
	// Zero or more optional `process.Process` instance used to transform images after having been rotated to fill the page and before being included in the final picturebook.
	RotateToFillPostProcess process.Process
	// An optional `caption.Caption` instance used to derive a caption string for each image added to the final picturebook.
	Caption caption.Caption
	// An optional `text.Text` instance used to derive a text string for each image added to the final picturebook.
	Text text.Text
	// An optional `sort.Sorter` instance used to sort images before they are added to the final picturebook.
	Sort sort.Sorter
	// A boolean value signaling that an image should be rotated if necessary to fill the maximum amount of any given page.
	FillPage bool
	// A boolean value to enable verbose logging during the creation of a picturebook.
	Verbose bool
	// A boolean value to enable to use of an OCRA font for writing captions.
	OCRAFont bool
	// A gocloud.dev/blob `Bucket` instance where source images are stored.
	Source *blob.Bucket
	// A gocloud.dev/blob `Bucket` instance where the final picturebook is written to.
	Target *blob.Bucket
	// A gocloud.dev/blob `Bucket` instance where are temporary files necessary in the creation of the picturebook are written to.
	Temporary *blob.Bucket
	// A boolean value signaling that images should only be added on even-numbered pages.
	EvenOnly bool
	// A boolean value signaling that images should only be added on odd-numbered pages.
	OddOnly bool
	// An optional value to indicate that a picturebook should not exceed this number of pages
	MaxPages int
	Logger   *slog.Logger
}

PictureBookOptions defines a struct containing configuration information for a given picturebook instance.

func NewPictureBookDefaultOptions 

func NewPictureBookDefaultOptions(ctx context.Context) (*PictureBookOptions, error)

NewPictureBookDefaultOptions returns a `PictureBookOptions` with default settings.

type PictureBookText 

type PictureBookText struct {
	// The name of the font to use for text strings.
	Font string
	// The style of the font to use for text strings.
	Style string
	// The size of the font to use for text strings.
	Size float64
	// The margin to apply to text strings.
	Margin float64
	// The colour of the font to use for text strings.
	Colour []int
}

type PictureBookText defines a struct for storing information for how text should be displayed in a picturebook.

Source Files

View all Source files

Directories

Path Synopsis
package application provides a common interface for picturebook-related applications.
 package application provides a common interface for picturebook-related applications.
commandline
package commandline provides a command-line application for creating picturebooks.
 package commandline provides a command-line application for creating picturebooks.
package caption provides a common interface for different mechanisms to derive captions for images.
 package caption provides a common interface for different mechanisms to derive captions for images.
cmd
picturebook
picturebook is a command-line application for creating a PDF file from a folder containing images.
 picturebook is a command-line application for creating a PDF file from a folder containing images.
package filter provides a common interfaces for filtering mechanisms used to determine inclusion in a picturebook.
 package filter provides a common interfaces for filtering mechanisms used to determine inclusion in a picturebook.
package picture provides methods and data structures for internal representations of images.
 package picture provides methods and data structures for internal representations of images.
package process provides a common interfaces for manipulating images before adding them to a picturebook.
 package process provides a common interfaces for manipulating images before adding them to a picturebook.
package sort provides a common interface for sorting a list of images to be included in a picturebook.
 package sort provides a common interface for sorting a list of images to be included in a picturebook.
package tempfile provides methods for working with temporary files used to create a picturebook.
 package tempfile provides methods for working with temporary files used to create a picturebook.
package text provides a common interface for different mechanisms to derive texts for images.
 package text provides a common interface for different mechanisms to derive texts for images.

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.