From 7282dec02773fc22bc6e3c26815758d3abb0ca34 Mon Sep 17 00:00:00 2001 From: radiospiel Date: Fri, 20 Apr 2012 02:28:10 +0200 Subject: [PATCH] Updates README, Usage --- README.md | 40 +++++++++++++++++++--------------------- app.rb | 37 +++++++++++++++++++------------------ 2 files changed, 38 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 145027a..96db7e7 100644 --- a/README.md +++ b/README.md @@ -44,16 +44,20 @@ wasting precious memory and CPU resources. To do so, just request `http:///[robot[/options]]*/uri`. Which and how many, if any, options are valid is specific to each robot. -The full URL syntax is `http:///[mode]/[format[quality]]/width/[height]/uri` +imgio currently supports these robots: ) -* **mode**: "fit", "fill", "scale_down", optional, defaults to "scale_down" -* **format**: "png" or "jpg", optional, defaults to "jpg" -* **quality**: the quality used when generating jpg, optional, defaults to 85 -* **width**: the width of the resulting image -* **height**: the height of the resulting image, optional, defaults to whatever height would match the original image's aspect ratio. -* **uri**: the URI to fetch the original image from +- **fit/x**: takes an image and produces a new image scaled down to fit into + x pixels. The image will never scaled up; if it is too small than + width and height will be adjusted to keep the requested aspect ratio. +- **fill/x**: takes an image and produces a new image scaled down to fit into + x pixels. The image will never scaled up; if it is too small than + width and height will be adjusted to keep the requested aspect ratio. +- **png**: convert the image into PNG format. Currently supported only in the left-most position. +- **jpg[/quality]**: convert the image into JPEG format. Currently supported only in the left-most position. # Deployment @@ -68,31 +72,25 @@ This script parses the URL you pass it, fetches the image at the URL, uses RMagi ### Caching is important -The HTTP response has the proper cache headers set to cache the result for 1 day (on default). That means -each requested image is built only a few times per day - assuming your webserver is configured to use a cache like [varnish](https://www.varnish-cache.org/). Hint: Heroku runs its instances behind a varnish cache. +The HTTP response has the proper cache headers set to cache the result for 1 day (on default). +That means each requested image is built only a few times per day - assuming your webserver +is configured to use a cache like [varnish](https://www.varnish-cache.org/). +Hint: Heroku runs its instances behind a varnish cache. # How to deploy -This is a simple sinatra application. Should work out of the box using the usual sinatra deployment options. +This is a simple sinatra application. Should work out of the box using the usual sinatra +deployment options. [How to deploy on heroku](http://blog.heroku.com/archives/2009/3/5/32_deploy_merb_sinatra_or_any_rack_app_to_heroku/) # Help improve this script (if you feel like doing so) - Clone. Extend. Fix. Send pull request. -Improvement areas are: - -- **error handling**: What happens if an URL is unresponsive? We certainly should not cache a 404 or something - similar, but we should not request the same URL over and over again. Any ideas welcome, especially when - they do not need a database or some other kind of "local" storage. -- **testing**: @sebastianspier contributed some tests that do real work, i.e. actually fetch images off the - net (thanks!). It would be nice though to have a) a web mock which just fake-delivers images, and b) some - code that actually compares generated images with expected ones. - ## Development * Make sure you have ImageMagick installed -* Imgio only works with ruby >= 1.9 Works with ruby 1.8.7 and ruby 1.9.2. +* Imgio only works with ruby >= 1.9. * Bundler is used for dependency management, so use `$ bundle install` to fetch the needed dependencies * You can run the included tests with `$ rake` diff --git a/app.rb b/app.rb index 008ebd2..15e5a68 100644 --- a/app.rb +++ b/app.rb @@ -63,28 +63,29 @@ EXAMPLES: - GET http://#{request.host_with_port}/120/90/http://www.google.de/images/srpr/logo3w.png - # => responds with the image scaled down to 120x90 - - GET http://#{request.host_with_port}/fill/120/90/http://www.google.de/images/srpr/logo3w.png + GET http://#{request.host_with_port}/fill/120x90/http://www.google.de/images/srpr/logo3w.png # => responds with the image filling a rectangle of 120x90 - - GET http://#{request.host_with_port}/fit/80/80/http://www.google.de/images/srpr/logo3w.png + + GET http://#{request.host_with_port}/fit/80x80/http://www.google.de/images/srpr/logo3w.png # => responds with the image fitting a rectangle of 80x80 - + DOCUMENTATION: - GET [mode]/[format[quality]]/width/[height]/uri - - width, height must be a positive integer - uri must adhere to URI specification - - Defaults: - - mode: scale_down - format: jpg - quality: 85 - height: whatever height would match the original image's aspect ratio + The URL describes an internal workflow. Think of it as a Unix shell pipe in left to right: the source URL + goes in, travels through different data processors ('robots'), and finally comes out of the workflow again. + The full URL syntax is `http:///#{request.host_with_port}/[robot[/options]]*/uri`. Which and how many, + if any, options are valid is specific to each robot. + + imgio currently supports these robots: ) + + - **fit/x**: takes an image and produces a new image scaled down to fit into + x pixels. The image will never scaled up; if it is too small than + width and height will be adjusted to keep the requested aspect ratio. + - **fill/x**: takes an image and produces a new image scaled down to fit into + x pixels. The image will never scaled up; if it is too small than + width and height will be adjusted to keep the requested aspect ratio. + - **png**: convert the image into PNG format. Currently supported only in the left-most position. + - **jpg[/quality]**: convert the image into JPEG format. Currently supported only in the left-most position. USAGE end