README
¶
go-iiif-uri
Go package for working with URIs in the go-iiif package (and friends).
Documentation
Documentation is incomplete.
Why does this package exist?
This package exists because the go-iiif:process code demands a URI interface because sometimes URIs are more complicated than simple strings. By extension the code in the go-iiif-aws package, which handles invoking the go-iiif:process code as ECS or Lambda task also needs to know about said URI interfaces.
If we put all the URI interfaces in go-iiif:process (which we did at first) we run in to the problem where the go-iiif-aws package needs to import go-iiif. Then we can no longer compile Linux binaries (in go-iiif-aws) on anything but a Linux machine because the go-iiif code is being invoked which in turn invokes bimg which invokes libvips which is not set up for cross-compiling.
That's it, really. It is a tiny bit sad-making but also not really a big deal.
URIs
go-iiif-uri URI strings are still a work in progress. While they may still change a bit around the edges efforts will be made to ensure backwards compatibility going forward.
Support for different go-iiif-uri URIs is supported using database/sql -like "drivers" for packages that support the URI interface:
type URI interface {
Scheme() string
String() string
Origin() string
Target(*url.Values) (string, error)
}
Schemes
go-iiif-uri URI strings are defined by a named scheme which indicates how an URI should be processed, a path which is a reference to an image and zero or more query parameters which are the specific instructions for processing the URI.
The following schemes are registed by default when you import go-iiif-uri.
file
file:///path/to/source/image.jpg
file:///path/to/source/image.jpg?target=/path/to/target/image.jpg
The file:// URI scheme is basically just a path or filename. It has an option target property which allows the name of the source image to be changed. These filenames are not the final name of the image as processed by go-iiif but the name of the directory structure that files will be written to, as in the weird IIIF instructions-based URIs.
Valid parameters for the file:// URI scheme are:
| Name | Type | Required |
|---|---|---|
| target | string | no |
idsecret
idsecret:///path/to/source/image.jpg?id=1234&secret=s33kret&secret_o=seekr3t&label
The idsecret:// URI scheme is designed to rewrite a source image URI to {UNIQUE_ID} + {SECRET} + {LABEL} style filenames. For example cat.jpg becomes 1234_s33kret_b.jpg and specifically 123/4/1234_s33kret_b.jpg where the unique ID is used to generate a nested directory tree in which the final image lives.
The idsecret:// URI scheme was developed for use with go-iiif "instructions" files where a single image produced multiple derivatives that need to share commonalities in their final URIs.
Valid parameters for the idsecret:// URI scheme are:
| Name | Type | Required |
|---|---|---|
| id | string | yes |
| label | string | yes |
| format | string | yes |
| original | string | no |
| secret | string | no |
| secret_o | string | no |
| prefix | string | no |
| ensure-int | bool | no |
If either the secret or secret_o parameters are absent they will be auto-generated.
The default prefix for idsecret URIs is to derive nested folders from the ID property. For example the default prefix for ID 34436377369 would be 344/363/773/69. You can override this by specifying a ?prefix={CUSTOM_PREFIX} in your idsecret:// URI string.
rewrite
rewrite:///path/to/source/image.jpg?target=/path/to/target/picture.jpg
The rewrite:// URI scheme is a variant of the file:// URI scheme except that the target query parameter is required and it will be used to redefine the final URI, rather than just its directory tree, of the processed image.
| Name | Type | Required |
|---|---|---|
| target | string | yes |
Example
Here's a excerpted example taken from the go-iiif process/parallel.go package that processes a single source image, defined as an idsecret:// URI, in to multiple derivatives defined in an "instructions" file.
The idsecret:// URI is output as a string using the instructions set to define the label and other query parameters. That string is then used to create a new rewrite:// URI where source is derived from the original idsecret:// URI and the target is newly generate URI string.
go func(u iiifuri.URI, label Label, i IIIFInstructions) {
var process_uri iiifuri.URI
switch u.Scheme() {
case "idsecret":
str_label := fmt.Sprintf("%s", label)
opts := &url.Values{}
opts.Set("label", str_label)
opts.Set("format", i.Format)
if str_label == "o" {
opts.Set("original", "1")
}
target_str, _ := u.Target(opts)
origin := u.Origin()
rw_str := fmt.Sprintf("%s?target=%s", origin, target_str)
rw_str = iiifuri.NewRewriteURIString(rw_str)
rw_uri, err := iiifuri.NewURI(rw_str)
process_uri = rw_uri
default:
process_uri = u
}
new_uri, im, _ := pr.ProcessURIWithInstructions(process_uri, label, i)
// do something with new_uri and im here...
}(u, label, i)
See also
Documentation
¶
Overview ¶
package uri provides interfaces and methods for the working with URIs in the `go-iiif` package.
Index ¶
Constants ¶
const FILE_SCHEME string = "file"
const IDSECRET_SCHEME string = "idsecret"
const REWRITE_SCHEME string = "rewrite"
Variables ¶
This section is empty.
Functions ¶
func RegisterURI ¶ added in v0.5.0
func RegisterURI(ctx context.Context, scheme string, f URIInitializeFunc) error
Types ¶
type IdSecretURI ¶
type IdSecretURI struct {
URI
// contains filtered or unexported fields
}
func (*IdSecretURI) Origin ¶
func (u *IdSecretURI) Origin() string
func (*IdSecretURI) Scheme ¶ added in v0.5.0
func (u *IdSecretURI) Scheme() string
func (*IdSecretURI) String ¶
func (u *IdSecretURI) String() string
type RewriteURI ¶
type RewriteURI struct {
URI
// contains filtered or unexported fields
}
func (*RewriteURI) Origin ¶
func (u *RewriteURI) Origin() string
func (*RewriteURI) Scheme ¶ added in v0.5.0
func (u *RewriteURI) Scheme() string
func (*RewriteURI) String ¶
func (u *RewriteURI) String() string
Source Files
Directories