English
资源说明：lightweight Python helper for resizing images with Pillow and optionally uploading to AmazonS3 with boto
## Overview
The `imagehelper` package offers a simple interface for image resizing,
optimizing and uploading image assets. Core image resizing operations are handled
by the `Pillow` (PIL) package; S3 uploading is handled by `boto3`, and there are
hooks for optimizing the images with the commandline tools: `advpng`, `gifsicle`,
`jpegtran`, `jpegoptim`, `optipng` and `pngcrush.`
This library does not actually resize the images, it is used to define "recipes"
for resizing images with Pillow and uploading them to S3 with boto3.
## About
`imagehelper` is a fork of internal image helping routines that were built for
FindMeOn.com around 2005. It has been actively maintained as an open source
project since at least 2012.
`imagehelper` allows you to define a schema for resizing images as a simple
`dict`, and will then easily resize them.
`imagehelper` also supports uploading the resized images - and an archival
version - onto Amazon's S3 service.
`imagehelper` requires `Pillow`. Earlier versions relied on `PIL` or supported
both. This really is an old package!
This package will try to import `boto3` for communicating with AmazonS3.
If you don't want to use S3, no worries - that is only optional and you can save
to a local file.
The package was originally aimed at thumbnails, but it works for all resizing
needs that are aimed at downsampling images.
If you have optimization applications like `gifsicle`, `pngcrush` and `jpegtran`
installed in your environment, you can 'optimize' the output (and archive) files.
This is a barebones package that has NO FRAMEWORK DEPENDENCIES - which is a good
thing. You define image transformation recipes using a simple dict, the
package does the rest.
This package also tries to avoid writing to disk whenever possible, tempfiles
(spooled) are avoided unless an external program is called. This package tries to
pipe everything through file-like in-memory objects.
I could only find a single tool for resizing thumbnails on PyPi that did not
require a framework, and that's really annoying.
The package is a bit awkard to use for a single task, but it was designed for
repetitive tasks - as in a web application.
A typical usage is illustrated in the sections below. Also check the `demo.py`
file to see how flexible this can be.
This package has been used in production for over a decade.
It supports Python2.7 and Python3. A lot of things could be done better and
should be done better, but this works and is relatively fast.
## Why ?
Imagine that you have a site that allows for user generated uploads, or you
want to make video stills...
You can create a schema of image sizes...
IMAGE_SIZES = {
'thumb': {
'width': 32,
'height': 32,
'save_quality': 50,
'suffix': 't1',
'format':'JPEG',
'constraint-method': 'fit-within',
'filename_template': '%(guid)s-120x120.%(format)s',
},
'og:image': {
'width': 200,
'height': 200,
'save_quality': 50,
'suffix': 'og',
'format':'JPEG',
'constraint-method': 'ensure-minimum',
'filename_template': '%(guid)s-og.%(format)s',
},
}
And easily upload them:
# create some configs in your app
# config object for IMAGE_SIZES
resizerConfig = imagehelper.resizer.ResizerConfig(
resizesSchema=IMAGE_SIZES,
optimize_original=True,
optimize_resized=True,
)
# config object for S3
saverConfig= imagehelper.saver.s3.SaverConfig(
key_public = AWS_KEY_PUBLIC,
key_private = AWS_KEY_SECRET,
bucket_public_name = AWS_BUCKET_PUBLIC,
bucket_archive_name = AWS_BUCKET_ARCHIVE,
)
# create some factories.
# factories are unnecessary. they just generate the workhorse objects for you
# they're very useful for cutting down code
# build one, then stash in your app
USE_FACTORY = True
if USE_FACTORY:
rFactory = imagehelper.resizer.ResizerFactory(resizerConfig=resizerConfig)
s3Factory = imagehelper.saver.s3.s3ManagerFactory(saverConfig=saverConfig, resizerConfig=rConfig, saverLogger=saverLogger)
resizer = rFactory.resizer()
s3Manager = s3Factory.saver_manager()
else:
resizer = imagehelper.resizer.Resizer(resizerConfig=resizerConfig)
s3Manager = imagehelper.saver.s3.s3Manager(saverConfig=saverConfig, resizerConfig=resizerConfig, saverLogger=saverLogger)
# resize !
resizedImages = resizer.resize(imagefile=get_imagefile())
# upload the resized items
uploaded_files = s3Manager.files_save(resizedImages, guid="123")
# want to delete them?
deleted = s3Manager.files_delete(uploaded_files)
Behind the scenes, imagehelper does all the math and uploading.
## Resizing Options
* `fit-within`
> Resizes item to fit within the bounding box, on both height and width.
> The resulting image will be the size of the bounding box or smaller.
* `fit-within:crop-to`
> Resizes the item along whichever axis ensures the bounding box is 100% full, then crops.
> The resulting image will be the size of the bounding box.
* `fit-within:ensure-width`
> Resizes item to fit within the bounding box, scaling height to ensure 100% width.
> The resulting image will be the size of the bounding box.
* `fit-within:ensure-height`
> Resizes item to fit within the bounding box, scaling width to ensure 100% height.
> The resulting image will be the size of the bounding box.
* `smallest:ensure-minimum`
> Resizes the item to cover the bounding box on both axis.
> One dimension may be larger than the bounding box.
* `exact:no-resize`
> Do not scale! Raises an exception if a scale must be made.
> This is a convenience for just saving/re-encoding files.
> For example, 100x100 must receive an image that is 100x100.
* `exact:proportion`
> Attempt to scale the image to an exact size. Raise an exception if it can't.
> Usually this is used to resample a 1:1 image, however this might be used to drop
> an image to a specific proportion. i.e. 300x400 can scale to 30x40, 300x400
> but not 30x50.
## Usage...
Check out the demo.py module - it offers a narrative demo of how to use the
package. Be sure to include some Amazon S3 credentials in your environment.
imagehelper is NOT designed for one-off resizing needs.
it's designed for a use in applications where you're repeatedly doing the same resizing.
The general program flow is this:
1. Create `Configuration` objects to hold instructions
2. Create `Factory` objects to hold the `Configuration` objects.
3. Obtain a `Worker` object from the `Factory` to do the actual work (resizing or uploading)
You should typically create "Configuration" and "Factory" objects during
application startup, and create/destroy a work for each request or event.
Here's a more in depth description
1. Create a dict of "photo resizes" describing your schema.
* keys prepended with `save_` are passed on to PIL during the call to `save`
(the prefix is removed)
* you can decide what type of resizing you want. sometimes you want to crop,
other times you want to fit within a box, other times you want to ensure a
height or width. this makes your designers happy.
2. create an array of `image_resizes_selected` -- the keys in the above schema
you want to resize.
3. you can pass these arguments into the routines themselves, or generate a
`imagehelper.resizer.ResizerConfig` object or a `imagehelper.resizer.ResizerFactory`
that you stash into your application.
4. If you're saving to AmazonS3, create an `imagehelper.saver.s3.SaverConfig`
config object to store your info. note that you can specify a public and
private bucket.
* resized thumbnails are saved to the public bucket
* the original item is optionally saved to the archive, which is not viewable to the public.
this is so you can do different sizing schemes in the future.
5. You can define your own Amazon S3 logger, a class that provides two methods:
class SaverLogger(object):
def log_save(self, bucket_name=None, key=None, file_size=None, file_md5=None):
pass
def log_delete(self, bucket_name=None, key=None):
pass
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
