Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 252 lines (154 sloc) 11.944 kb
cc16b51 update readme introduction
Francesc Ortiz authored
1 ## Introduction
2
25c668d update readme instroduction
Francesc Ortiz authored
3 I've seen some plugins that allow you to set the crop images by dragging and resizing a selection area over the original image. The problem with this method is that you need to know cropped sizes when you upload the images and, if there is a change in the design, you have to do all the crops again.
cc16b51 update readme introduction
Francesc Ortiz authored
4
5 Also, many thumbnailers forget about videos.
6
25c668d update readme instroduction
Francesc Ortiz authored
7 This is why I created this image resizing library for django, in which you set the center of attention of an image (or video) and cropping is done **automatically keeping the center of attention** as close to the center of the image as possible. Thanks to this, when people's faces or the significant element of a picture are not centered, you can relay on automatic cropping confident that those items will be respected.
cc16b51 update readme introduction
Francesc Ortiz authored
8
25c668d update readme instroduction
Francesc Ortiz authored
9 Appart from that, I keep adding the functionalities that I need as I come into new projects. Thanks to this, you can see features like **masking, multiple overlays, tint, fill color** or **background color**.
cc16b51 update readme introduction
Francesc Ortiz authored
10
a7f6f26 update readme introduction
Francesc Ortiz authored
11 On a more technical side, another feature of image is that **it does not use presets**. You just set the parameters that you want to use on each place, allowing you to quickly implement it and to easily integrate image with other code. For server security and stability, it relays on tokens and disk cache to keep the server in peace. If you publish this disk cache through **mod_rewrite** or equivalents, you can even skip django from getting image requests.
cc16b51 update readme introduction
Francesc Ortiz authored
12
c709f15 update readme
Francesc Ortiz authored
13 ### What's new
15e681c update readme
Francesc Ortiz authored
14
491f85e update readme
Francesc Ortiz authored
15 **May 2012**
16
34d744e faser tint
Francesc Ortiz authored
17 - parameter "tint=RRGGBBAA" or "tint=RRGGBBAAII":
18 Tints the image. Works equal to overlays.
19 See below.
20
21 **May 2012**
22
491f85e update readme
Francesc Ortiz authored
23 - parameter "overlay_source=media":
24 looks for overlay image in MEDIA_ROOT instead of STATIC_ROOT
25
26 - parameter "overlay_tint=RRGGBBAA" or "overlay_tint=RRGGBBAAII":
27 Tints the overlay.
28 See below.
29
30 - support for multiple overlays:
31 See below.
32
aa64420 udpate readme
Francesc Ortiz authored
33 **April 2012**
34
35 - make it compatible with django 1.4
36
37 - make it compatible with django-reversion.
38
39 - parameter "autogen=true":
40 Add support for precreation of images.
41 Allows external linking, good for newsletters and others
42
43 - parameter "background=RRGGBBAA":
44 Allow to set background color to an RGBA hex value.
45 Applied before mask and overlay.
46
47 - parameter "fill=RRGGBBAA":
48 When using "mode=scale", allow to force size of output image
49 to target with and height.
50 You have to pass and RGBA hex value that will be set as background color.
51 Applied before mask and overlay.
52
53 **December 2011**
54
34e976a update readme
Francesc Ortiz authored
55 Masking, working with static files, possiblity of telling format and quality.
8590c37 update readme
Francesc Ortiz authored
56 Show error images instead of raising exceptions.
34e976a update readme
Francesc Ortiz authored
57
aa64420 udpate readme
Francesc Ortiz authored
58 Significant update: now you have to {% load img %} instead of {% load image %}
59
15e681c update readme
Francesc Ortiz authored
60
8ca74d6 update readme
Francesc Ortiz authored
61 ## settings variables
62
63 ### Context Processors
64
65 'django.core.context_processors.request' is mandatory because the image tag uses sessions.
66
67 ### Custom settings
9ade70c @francescortiz README.markup
authored
68
69 * **IMAGE_CACHE_ROOT**: It is the filesystem path where you want cache to be stored. You can use a web public directory. This way, with the appropiate .htaccess rules or server configuration, you can delegate to the http server thumbnail submission once they are already created.
70
d05f3e5 show and image with an error text isntead of raising an error when an…
Francesc Ortiz authored
71 * **IMAGE_DEFAULT_FORMAT**: (default='JPEG') It is the filesystem path where you want cache to be stored. You can use a web public directory. This way, with the appropiate .htaccess rules or server configuration, you can delegate to the http server thumbnail submission once they are already created.
8ca74d6 update readme
Francesc Ortiz authored
72
d05f3e5 show and image with an error text isntead of raising an error when an…
Francesc Ortiz authored
73 * **IMAGE_DEFAULT_QUALITY**: (default=85) It is the filesystem path where you want cache to be stored. You can use a web public directory. This way, with the appropiate .htaccess rules or server configuration, you can delegate to the http server thumbnail submission once they are already created.
74
75 * **IMAGE_FONT_FILE**: (default=[image package path]/FreeFont.ttf) The font file to use for error messages.
76
77 * **IMAGE_FONT_LINE_HEIGHT**: (default=.7) A base 1 percentage (1 equals 100%) to set line height for the font.
78
79 * **IMAGE_FONT_BACKGROUND**: ( default=(255,255,255,255) ) Background color for errors. RGBA format
80
81 * **IMAGE_FONT_LINE_HEIGHT**: ( default=(0,0,0,255) ) Foreground color for errors. RGBA format
82
83 * **IMAGE_ERROR_NOT_FOUND**: ( default="Image not found" ) Text to show when an image is not found.
84
85 * **IMAGE_ERROR_NOT_VALID**: ( default="Image not valid" ) Text to show when an image is not valid.
8ca74d6 update readme
Francesc Ortiz authored
86
6c09fb3 show error images with videos
Francesc Ortiz authored
87 * **IMAGE_ERROR_VIDEO_NOT_FOUND**: ( default="Video not found" ) Text to show when a video is not found.
88
89 * **IMAGE_ERROR_FFMPEG**: ( default="Video error" ) Text to show when ffmpeg fails.
90
2077a13 Handle worng requests
Francesc Ortiz authored
91 * **IMAGE_WRONG_REQUEST**: (default="Wrong request" ) Text to show when the request is wrong
92
8ca74d6 update readme
Francesc Ortiz authored
93 ### Dependency on django settings
94
95 * **STATIC_ROOT**: Only if you use overlay or mask.
96
97 * **FILE_UPLOAD_TEMP_DIR**: Used to store temporary images when working with videos.
98
9ade70c @francescortiz README.markup
authored
99 ## Custom fields
100 It adds two custom fields you can use with your models:
101
102 * **ImageCenterField**: you only have to provide the **image_field** argument. It has to be the ImageField or VideoField it references. **It also provides thumbnail preview in the admin section** when in edit mode.
8ca74d6 update readme
Francesc Ortiz authored
103 * **VideoField**: It is just a FileField with another signature.
9ade70c @francescortiz README.markup
authored
104
105 ## Template tags
8ca74d6 update readme
Francesc Ortiz authored
106 You have to {% load img %} in your templates:
107 ###{% image [source] [parameters] %}
9ade70c @francescortiz README.markup
authored
108 Returns an url that points to the thumbnail.
109
8ca74d6 update readme
Francesc Ortiz authored
110 * **source**: Either a path or an ImageField or VideoField instance. It doesn't necessarely needs to have a related ImageCenterField.
9ade70c @francescortiz README.markup
authored
111 * **parameters**: string of a list of parameters in querystring format. See parameters section
112
113 ## URLs
114 It provides two URLs:
115
116 * /image/(?P\<**path**\>)/(?P\<**parameters**\>): It is this view that actually does the work. **path** will be searched in the directory settings.MEDIA_ROOT. See below for **parameters**.
117 * /image-crosshair: Just a base64 encoded png to use in the admin section.
118
491f85e update readme
Francesc Ortiz authored
119 ## Overlays
120 You can have multiple overlays, each one with its overlay_source and its overlay_tint.
a311292 fix readme
Francesc Ortiz authored
121
34d744e faser tint
Francesc Ortiz authored
122 ### overlay_tint=RRGGBBAAII
a311292 fix readme
Francesc Ortiz authored
123
97cd3b1 fix readme
Francesc Ortiz authored
124 II stands for Intensity. Values from 00 to ff. Ammount of tint to apply.
491f85e update readme
Francesc Ortiz authored
125
34d744e faser tint
Francesc Ortiz authored
126 AA and II are optional.
127
128 If AA smaller than ff, the layer will become transparent.
a311292 fix readme
Francesc Ortiz authored
129
34d744e faser tint
Francesc Ortiz authored
130 Accepts value None (overlay_tint=None).
97cd3b1 fix readme
Francesc Ortiz authored
131
f784038 fix readme
Francesc Ortiz authored
132 ### overlay_source=media/static
133
134 Where to look for overlay, either MEDIA_ROOT or STATIC_ROOT
135
136 ### Examples:
97cd3b1 fix readme
Francesc Ortiz authored
137
138 overlay=test/img0.png&overlay_tint=**ff0000ff**&overlay=test/img1.png&overlay_tint=**00ff0077**
139
140 overlay=test/img0.png&overlay_tint=**None**&overlay=test/img1.png&overlay_tint=**00ff0077aa**
141
142 overlay=test/img0.png&overlay_source=**media**&overlay=test/img1.png&overlay_source=**static**
491f85e update readme
Francesc Ortiz authored
143
144 ## Caution with overlays
145 **If you use overlay_tint or overlay_source, the position in which they appear does not matter**.
a311292 fix readme
Francesc Ortiz authored
146
491f85e update readme
Francesc Ortiz authored
147 The order of appearances is used to associate overlays with overlay_tints and overlay_sources. In other words, the first appearance of overlay_tint is associated with the first overlay. The same applies for overlay_source.
a311292 fix readme
Francesc Ortiz authored
148
97cd3b1 fix readme
Francesc Ortiz authored
149 ### These two are equivalent:
150
151 overlay=test/img0.png&**overlay_tint=ff0000ff**&overlay=test/img1.png
a311292 fix readme
Francesc Ortiz authored
152
97cd3b1 fix readme
Francesc Ortiz authored
153 overlay=test/img0.png&overlay=test/img1.png**&overlay_tint=ff0000ff**
a311292 fix readme
Francesc Ortiz authored
154
97cd3b1 fix readme
Francesc Ortiz authored
155 ### To tint only the second overlay, you have to do this:
a311292 fix readme
Francesc Ortiz authored
156
97cd3b1 fix readme
Francesc Ortiz authored
157 overlay=test/img0.png**&overlay_tint=None**&overlay=test/img1.png**&overlay_tint=ff0000ff**
491f85e update readme
Francesc Ortiz authored
158
9ade70c @francescortiz README.markup
authored
159 ## Parameters
160 Parameters are supplied in query string format.
161
162 ### Common Parameters
163
8ca74d6 update readme
Francesc Ortiz authored
164 * **width**: [required] target width. Set it to a big number if you are scaling to fit vertically.
165 * **height**: [required] target height. Set it to a big number if you are scaling to fit horizontally.
166 * **mode**: "scale" or "crop". Defaults to "crop". "scale" will fit the image to the given width and height without loosing proportions. "crop" will fill the given area cropping if necessary.
491f85e update readme
Francesc Ortiz authored
167 * **overlay** (multiple values accepted): and overlay image to add on top of the image. It won't be resized. I use it to place a play button on top of video thumbnails. Overlay search path is STATIC_ROOT.
168 * **overlay_source=media/static** (multiple values accepted): tells where to look for the overlay, either MEDIA_ROOT or STATIC_ROOT.
34d744e faser tint
Francesc Ortiz authored
169 * **overlay_tint=RRGGBB overlay_tint=RRGGBBAA overlay_tint=RRGGBBAAII** (multiple values accepted): tints the overlay. II stands for intensity. AA different to ff makes the overlay transparent.
280d4ea - make mask size adjust to rendered image size
Francesc Ortiz authored
170 * **mask**: a mask image. the mask will be resized to the rendered image size. Mask search path is STATIC_ROOT. **If you set a mask, format switches automatically to PNG**
8ca74d6 update readme
Francesc Ortiz authored
171 * **static**: tells image to look for our image in STATIC_ROOT instead of MEDIA_ROOT.
172 * **format**: one of JPG, PNG, etc.
173 * **quality**: quality to use for "format"
2418eaa udpate readme
Francesc Ortiz authored
174 * **autogen**: if set, the image will be pregenerated, allowing external linking (newsletters, etc).
175 * **background=RRGGBBAA**: if set, background color to apply to the image (only makes sense on transparent images).
176 * **fill=RRGGBBAA**: forces the size of the generated image to be the request width and height. Unless "mode" is set to "scale", it behaves exactly as "background=RRGGBBAA".
34d744e faser tint
Francesc Ortiz authored
177 * **tint=RRGGBB tint=RRGGBBAA tint=RRGGBBAAII**: tints the image. Works like overlay_tint.
2418eaa udpate readme
Francesc Ortiz authored
178
8ca74d6 update readme
Francesc Ortiz authored
179
180 ### Other parameters
181
42f7a72 Update readme
Francesc Ortiz authored
182 * **url**: make a thumbnail of the given url. If url is given, [source] is ignored.
9ade70c @francescortiz README.markup
authored
183
8ca74d6 update readme
Francesc Ortiz authored
184 These next two parameters don't make sense if you are thumbnailing an ImageField or VideoField, because if so image takes care of them automatically.
9ade70c @francescortiz README.markup
authored
185
186 * **video**: If the key exists we are going to create a thumbnail of a video.
187 * **center**: center of attention. You have to provide X and Y as base 1 percentages. For example, "center=0.5,0.5" will set the center of attention to the center of the image.
188
8ca74d6 update readme
Francesc Ortiz authored
189
9ade70c @francescortiz README.markup
authored
190 ## Admin Section
8ca74d6 update readme
Francesc Ortiz authored
191 This is how ImageCenter looks in the admin section when it is editable. **Just click on the the center of attention of the image and save.**
9ade70c @francescortiz README.markup
authored
192
3709bac @francescortiz Edited README.markdown via GitHub
authored
193 ![Screenshot](https://github.com/francescortiz/image/wiki/admin_section.png)
9ade70c @francescortiz README.markup
authored
194
195 ## Background features
196
197 * Thumbnails are automatically removed when database entries are removed.
198 * It does not use any templates or resources. Just setup urls.py and done.
199 * South integration: custom fields are understood by south.
2418eaa udpate readme
Francesc Ortiz authored
200 * Unless "autogen=true" is set, it prevents external linking.
201 * If you set IMAGE_CACHE_ROOT to a directory that is in your public http directory, you can use mod_rewrite or equivalents to have the HTTP server serve the resized images directly.
9ade70c @francescortiz README.markup
authored
202
203 ## Dependencies
204
205 * **PIL**: python imaging library is used for image manipualtion. If you want to handle transparency you need at least PIL 1.1.7
206 * **ffmpeg**: only if you want video thumbnails.
207
208 ## Known issues
8ca74d6 update readme
Francesc Ortiz authored
209 I develop as I need to. Open an issue if you need to fix something or demand any other feature.
9ade70c @francescortiz README.markup
authored
210
211 * help_text kwarg does not work for ImageCenterField
212
213 ## Examples
214
215 Sample model:
216
217 class Test(models.Model):
218
219 image = ImageField(upload_to="test")
220 image_center = ImageCenterField(image_field=image)
221 video = VideoField(upload_to="test")
222 video_center = ImageCenterField(image_field=video)
223
224 Sample urls.py:
225
226 # -*- coding: UTF-8 -*-
227 from django.conf.urls.defaults import *
228 from django.contrib import admin
229 admin.autodiscover()
230
231 urlpatterns = patterns('',
232 (r'^admin/', include(admin.site.urls)),
233 (r'^', include('image.urls')),
234 )
235
236 Sample template:
237
8ca74d6 update readme
Francesc Ortiz authored
238 {% load img %}
239 <img src="{% image test.image 'width=150&height=150&format=JPEG&quality=95' %}"/>
240 <img src="{% image test.video 'width=150&height=150&format=PNG' %}"/>
241 <img src="{% image path_variable 'width=150&height=150&mode=scale&static=true' %}"/>
2418eaa udpate readme
Francesc Ortiz authored
242 <img src="{% image '' 'url=http://www.example.com/img.jpg&width=150&height=150&mode=scale&overlay=img/overlay.png' %}"/>
9ade70c @francescortiz README.markup
authored
243
2fec60c update readme
Francesc Ortiz authored
244 ## TODO
245
246 * Remove the need to specify with and height for images beeing manipulated. Let the system work with the original image size.
247 * Add the posibility to prevent upscaling.
248 * Make it possible to set the size of the center of attention, in order to be able to make crops that only show that area.
249
250
251
Something went wrong with that request. Please try again.