Merge pull request #8 from why404/master

新增 高级图像处理方法（缩略、裁剪、旋转、转化），支持结果持久化存储

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    qiniu-rs (2.1.2)
+    qiniu-rs (2.2.1)
       json (~> 1.7.3)
       mime-types (~> 1.19)
       rest-client (~> 1.6.7)

docs/README.md

@@ -30,6 +30,8 @@ title: Ruby SDK 使用指南 | 七牛云存储
     - [图像处理](#op-image)
         - [查看图片属性信息](#image_info)
         - [获取指定规格的缩略图预览地址](#image_preview_url)
+        - [高级图像处理（缩略、裁剪、旋转、转化）](#image_mogrify_preview_url)
+        - [高级图像处理（缩略、裁剪、旋转、转化）并持久化](#image_mogrify_save_as)
 
 - [贡献代码](#Contributing)
 - [许可证](#License)
@@ -500,6 +502,114 @@ spec
 返回一个字符串类型的缩略图 URL
 
 
+<a name="image_mogrify_preview_url"></a>
+
+#### 高级图像处理（缩略、裁剪、旋转、转化）
+
+`Qiniu::RS.image_mogrify_preview_url()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，该方法返回一个可以直接预览缩略图的URL。
+
+    image_mogrify_preview_url = Qiniu::RS.image_mogrify_preview_url(source_image_url, mogrify_options)
+
+**参数**
+
+source_image_url
+: 必须，字符串类型（string），指定原始图片的下载链接，可以根据 rs.get() 获取到。
+
+mogrify_options
+: 必须，Hash Map 格式的图像处理参数。
+
+`mogrify_options` 对象具体的规格如下：
+
+    mogrify_options = {
+        :thumbnail => <ImageSizeGeometry>,
+        :gravity => <GravityType>, =NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast
+        :crop => <ImageSizeAndOffsetGeometry>,
+        :quality => <ImageQuality>,
+        :rotate => <RotateDegree>,
+        :format => <DestinationImageFormat>, =jpg, gif, png, tif, etc.
+        :auto_orient => <TrueOrFalse>
+    }
+
+`Qiniu::RS.image_mogrify_preview_url()` 方法是对七牛云存储图像处理高级接口的完整包装，关于 `mogrify_options` 参数里边的具体含义和使用方式，可以参考文档：[图像处理高级接口](#/v2/api/foimg/#fo-imageMogr)。
+
+**返回值**
+
+返回一个可以预览最终缩略图的URL，String 类型。
+
+
+<a name="image_mogrify_save_as"></a>
+
+#### 高级图像处理（缩略、裁剪、旋转、转化）并持久化存储处理结果
+
+`Qiniu::RS.image_mogrify_save_as()` 方法支持将一个存储在七牛云存储的图片进行缩略、裁剪、旋转和格式转化处理，并且将处理后的缩略图作为一个新文件持久化存储到七牛云存储服务器上，这样就可以供后续直接使用而不用每次都传入参数进行图像处理。
+
+    result = Qiniu::RS.image_mogrify_save_as(target_bucket, target_key, src_img_url, mogrify_options)
+
+**参数**
+
+target_bucket
+: 必须，字符串类型（string），指定最终缩略图要存放的 bucket 。
+
+target_key
+: 必须，字符串类型（string），指定最终缩略图存放在云存储服务端的唯一文件ID。
+
+src_img_url
+: 必须，字符串类型（string），指定原始图片的下载链接，可以根据 rs.get() 获取到。
+
+mogrify_options
+: 必须，Hash Map 格式的图像处理参数。
+
+`mogrify_options` 对象具体的规格如下：
+
+    mogrify_options = {
+        :thumbnail => <ImageSizeGeometry>,
+        :gravity => <GravityType>, =NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast
+        :crop => <ImageSizeAndOffsetGeometry>,
+        :quality => <ImageQuality>,
+        :rotate => <RotateDegree>,
+        :format => <DestinationImageFormat>, =jpg, gif, png, tif, etc.
+        :auto_orient => <TrueOrFalse>
+    }
+
+`Qiniu::RS::Image.mogrify_preview_url()` 方法是对七牛云存储图像处理高级接口的完整包装，关于 `mogrify_options` 参数里边的具体含义和使用方式，可以参考文档：[图像处理高级接口](#/v2/api/foimg/#fo-imageMogr)。
+
+**返回值**
+
+如果请求失败，返回 `false`；否则，返回如下一个 `Hash` 类型的结构：
+
+    {"hash" => "FrOXNat8VhBVmcMF3uGrILpTu8Cs"}
+
+示例代码：
+
+    data = Qiniu::RS.get("<test_image_bucket>", "<test_image_key>")
+    src_img_url = data["url"]
+
+    target_bucket = "test_thumbnails_bucket"
+    target_key = "cropped-" + @test_image_key
+
+    mogrify_options = {
+      :thumbnail => "!120x120r",
+      :gravity => "center",
+      :crop => "!120x120a0a0",
+      :quality => 85,
+      :rotate => 45,
+      :format => "jpg",
+      :auto_orient => true
+    }
+
+    result = Qiniu::RS.image_mogrify_save_as(target_bucket, target_key, src_img_url, mogrify_options)
+    if result
+      thumbnail = Qiniu::RS.get(target_bucket, target_key)
+      puts thumbnail["url"]
+
+      # 您可以选择将存放缩略图的 bucket 公开，这样就可以直接以外链的形式访问到缩略图，而不用走API获取下载URL。
+      result = Qiniu::RS.publish("pic.example.com", target_bucket)
+
+      # 然后将 pic.example.com CNAME 到 iovip.qbox.me ，就可以直接以如下方式访问缩略图
+      # [GET] http://pic.example.com/<target_key>
+    end
+
+
 <a name="Contributing"></a>
 
 ## 贡献代码

lib/qiniu/rs.rb

@@ -118,6 +118,15 @@ module Qiniu
         Image.preivew_url(url, spec)
       end
 
+      def image_mogrify_preview_url(source_image_url, options)
+        Image.mogrify_preview_url(source_image_url, options)
+      end
+
+      def image_mogrify_save_as(bucket, key, source_image_url, options)
+        code, data = RS.image_mogrify_save_as(bucket, key, source_image_url, options)
+        code == StatusOK ? data : false
+      end
+
       #def generate_upload_token(scope, expires_in, callback_url = nil, return_url = nil)
       #  Utils.generate_upload_token(scope, expires_in, callback_url, return_url)
       #end

lib/qiniu/rs/image.rb

@@ -14,6 +14,24 @@ module Qiniu
           url + '/imagePreview/' + spec.to_s
         end
 
+        def mogrify_preview_url(source_image_url, options)
+          source_image_url + '?' + generate_mogrify_params_string(options)
+        end
+
+        def generate_mogrify_params_string(options = {})
+          opts = {}
+          options.each do |k, v|
+            opts[k.to_s] = v
+          end
+          params_string = ""
+          keys = ["thumbnail", "gravity", "crop", "quality", "rotate", "format"]
+          keys.each do |key|
+            params_string += %Q(/#{key}/#{opts[key]}) unless opts[key].nil?
+          end
+          params_string += '/auto-orient' unless opts["auto_orient"].nil?
+          'imageMogr' + params_string
+        end
+
       end
     end
   end

lib/qiniu/rs/rs.rb

@@ -57,6 +57,18 @@ module Qiniu
           batch("delete", bucket, keys)
         end
 
+        def save_as(bucket, key, source_url, op_params_string)
+          encoded_uri = encode_entry_uri(bucket, key)
+          save_as_string = '/save-as/' + encoded_uri
+          new_url = source_url + '?' + op_params_string + save_as_string
+          Auth.request new_url
+        end
+
+        def image_mogrify_save_as(bucket, key, source_image_url, options)
+          mogrify_params_string = Image.generate_mogrify_params_string(options)
+          save_as(bucket, key, source_image_url, mogrify_params_string)
+        end
+
       end
     end
   end

lib/qiniu/rs/version.rb

@@ -2,6 +2,6 @@
 
 module Qiniu
   module RS
-    VERSION = "2.1.2"
+    VERSION = "2.2.1"
   end
 end

spec/qiniu/rs/image_spec.rb

@@ -9,7 +9,7 @@ module Qiniu
   module RS
     describe Image do
 
-      before :each do
+      before :all do
 =begin
         code, data = Qiniu::RS::Auth.exchange_by_password!("test@qbox.net", "test")
         code.should == 200
@@ -20,11 +20,15 @@ module Qiniu
         puts data.inspect
 =end
 
-        @bucket = "test_images"
+        @bucket = "test_images_12345"
         @key = "image_logo_for_test.png"
 
         local_file = File.expand_path('../' + @key, __FILE__)
 
+        result = Qiniu::RS.drop(@bucket)
+        result.should_not be_false
+        puts result.inspect
+
         put_url = Qiniu::RS.put_auth(10)
         put_url.should_not be_false
         put_url.should_not be_empty
@@ -32,21 +36,42 @@ module Qiniu
                                   :file => local_file,
                                   :bucket => @bucket,
                                   :key => @key,
+                                  :mime_type => "image/png",
                                   :enable_crc32_check => true
         result.should be_true
+
+
+        result = Qiniu::RS.get(@bucket, @key)
+        result["url"].should_not be_empty
+        puts result.inspect
+        @source_image_url = result["url"]
+
+        @mogrify_options = {
+            :thumbnail => "!120x120r",
+            :gravity => "center",
+            :crop => "!120x120a0a0",
+            :quality => 85,
+            :rotate => 45,
+            :format => "jpg",
+            :auto_orient => true
+        }
       end
 
       context ".info" do
         it "should works" do
-          result = Qiniu::RS.get(@bucket, @key)
-          result["url"].should_not be_empty
-          puts result.inspect
-          code, data = Qiniu::RS::Image.info(result["url"])
+          code, data = Qiniu::RS::Image.info(@source_image_url)
           code.should == 200
           puts data.inspect
         end
       end
 
+      context ".mogrify_preview_url" do
+        it "should works" do
+          mogrify_preview_url = Qiniu::RS::Image.mogrify_preview_url(@source_image_url, @mogrify_options)
+          puts mogrify_preview_url.inspect
+        end
+      end
+
     end
   end
 end

spec/qiniu/rs_spec.rb

@@ -10,6 +10,9 @@ module Qiniu
       @bucket = 'qiniu_rs_test'
       @key = Digest::SHA1.hexdigest Time.now.to_s
       @domain = 'cdn.example.com'
+
+      @test_image_bucket = 'test_images_12345'
+      @test_image_key = 'image_logo_for_test.png'
     end
 
 =begin
@@ -138,7 +141,7 @@ module Qiniu
 
     context ".image_info" do
       it "should works" do
-        data = Qiniu::RS.get("test_images", "image_logo_for_test.png")
+        data = Qiniu::RS.get(@test_image_bucket, @test_image_key)
         data.should_not be_false
         data.should_not be_empty
         puts data.inspect
@@ -149,6 +152,32 @@ module Qiniu
       end
     end
 
+    context ".image_mogrify_save_as" do
+      it "should works" do
+        data = Qiniu::RS.get(@test_image_bucket, @test_image_key)
+        data.should_not be_false
+        data.should_not be_empty
+        puts data.inspect
+
+        dest_bucket = "test_thumbnails_bucket"
+        dest_key = "cropped-" + @test_image_key
+        src_img_url = data["url"]
+        mogrify_options = {
+          :thumbnail => "!120x120r",
+          :gravity => "center",
+          :crop => "!120x120a0a0",
+          :quality => 85,
+          :rotate => 45,
+          :format => "jpg",
+          :auto_orient => true
+        }
+        result = Qiniu::RS.image_mogrify_save_as(dest_bucket, dest_key, src_img_url, mogrify_options)
+        result.should_not be_false
+        result.should_not be_empty
+        puts result.inspect
+      end
+    end
+
     context ".generate_upload_token" do
       it "should works" do
         data = Qiniu::RS.generate_upload_token({:scope => 'test_bucket', :expires_in => 3600})