文档

自定义裁剪

更新时间:

如果您希望获取指定大小的OSS图片,以适配网页元素或者满足排版格式的要求,您可以使用自定义裁剪功能。

使用场景

  • 网页设计与制作:在设计网页布局时,可能需要将图片裁剪成特定尺寸以适应网页元素,如头像、背景图、产品展示图等。

  • 社交媒体发布:不同社交媒体平台对图片上传有各自的尺寸要求,例如封面照片、帖子图片、故事图片等,您需要按照推荐尺寸进行图片裁剪,以达到最佳展示效果。

  • 移动应用开发:App中的图标、启动页、内嵌图片等都需要按规格裁剪,确保在不同分辨率和屏幕尺寸的设备上都能正确显示。

  • 图像数据库管理:对于拥有大量图像资源的机构,例如图书馆、档案馆等,整理和归档时可能需要统一裁剪图片至预设尺寸。

注意事项

  • 如果指定起点的横纵坐标大于原图,将会返回BadRequest错误,错误信息为Advance cut's position is out of image.

  • 如果从起点开始指定的宽度和高度超过了原图,将会直接裁剪到原图边界为止。

  • 您可以通过文件URL、SDK、API方式设置图片处理参数。本文以文件URL为例进行介绍,人脸裁剪和智能算法裁剪示例除外。文件URL仅适用于公共访问的图片。如果是私有访问的图片,请使用SDK、API处理图片。更多信息,请参见图片处理操作方式

参数说明

操作名称:crop

参数说明如下:

参数

描述

取值范围

w

指定裁剪宽度。

[0,图片宽度]

默认为最大值。

h

指定裁剪高度。

[0,图片高度]

默认为最大值。

x

指定裁剪起点横坐标(默认左上角为原点)。

[0,图片边界]

y

指定裁剪起点纵坐标(默认左上角为原点)。

[0,图片边界]

g

设置裁剪的原点位置。原点按照九宫格的形式分布,一共有九个位置可以设置。

  • nw:左上

  • north:中上

  • ne:右上

  • west:左中

  • center:中部

  • east:右中

  • sw:左下

  • south:中下

  • se:右下

  • face:最大人脸

  • auto:自动

说明

face和auto参数相关说明如下:

  • 需要先绑定IMM Project。关于控制台和API如何绑定,请参见快速入门AttachOSSBucket

  • 不支持匿名访问。

  • 必须拥有IMM处理所需的相关权限。更多信息,请参见权限

  • auto参数会忽略传入的w、h、p参数,以算法推荐的w和h为准。

关于各裁剪原点位置的计算方法,请参见计算方法

p

倍率参数。

[1,200],以百分比为单位。

说明

仅当设置g_face时该参数生效。

各裁剪原点位置的计算方法如下。其中srcW代表原图宽度,srcH代表原图高度。

裁剪原点

位置计算方法

nw

0, 0

north

srcW/2 - w/2, 0

ne

srcW - w, 0

west

0, srcH/2 - h/2

center

srcW/2 - w/2, srcH/2 - h/2

east

srcW - w, srcH/2 - h/2

sw

0, srcH - h

south

srcW/2 - w/2, srcH - h

se

srcW - w, srcH - h

操作方式

自定义裁剪公共读或者公共读写的图片

您可以通过在文件URL中直接添加图片处理参数的方式,自定义裁剪公共读或者公共读写的图片。

本示例使用杭州地域名为oss-console-img-demo-cn-hangzhou-3az的Bucket,图片外网访问地址为:

https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg原图

自定义裁剪私有图片(无需绑定IMM)

以本示例中的原图为例,将原图右下角作为裁剪起点,裁减范围为900 px*900 px。

Java

要求使用3.17.4及以上版本的Java SDK。

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;

public class Demo {
    public static void main(String[] args) throws Throwable {
        // Endpoint以华东1(杭州)为例,其它Region请按实际情况填写。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填写Endpoint对应的Region信息,例如cn-hangzhou。
        String region = "cn-hangzhou";
        // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填写Bucket名称,例如examplebucket。
        String bucketName = "examplebucket";
        // 填写原图完整路径。Object完整路径中不能包含Bucket名称。
        String objectName = "example.jpg";
        // 填写自定义裁剪后保存到本地文件的完整路径,例如D:\\dest.jpg。如果指定的本地文件存在会覆盖,不存在则新建。
        String pathName = "D:\\dest.jpg";

        // 创建OSSClient实例。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // 以原图右下角作为裁剪起点,裁减范围为900 px*900 px。
            String image = "image/crop,w_900,h_900,g_se";
            GetObjectRequest request = new GetObjectRequest(bucketName, objectName);
            request.setProcess(image);
            // 将处理后的图片保存到本地。
            // 如果未指定本地路径只填写了文件名称(例如dest.jpg),则文件默认保存到示例程序所属项目对应本地路径中。
            ossClient.getObject(request, new File("D:\\dest.jpg"));
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

PHP

要求使用PHP SDK 2.7.0及以上版本。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;

// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
$provider = new EnvironmentVariableCredentialsProvider();
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填写Bucket名称,例如examplebucket。
$bucket= "examplebucket";
// 填写原图完整路径。Object完整路径中不能包含Bucket名称。
$object = "src.jpg";
// 填写自定义裁剪后保存到本地文件的完整路径,例如D:\\dest.jpg。如果指定的本地文件存在会覆盖,不存在则新建。
// 如果未指定本地路径只填写了本地文件名称(例如dest.jpg),则文件默认保存到示例程序所属项目对应本地路径中。
$download_file = "D:\\dest.jpg";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        // 填写阿里云通用Region ID。
        "region" => "cn-hangzhou"
    );
$ossClient = new OssClient($config);

// 以原图右下角作为裁剪起点,裁剪范围为900 px*900 px。
$image = "image/crop,w_900,h_900,g_se";

$options = array(
    OssClient::OSS_FILE_DOWNLOAD => $download_file,
    OssClient::OSS_PROCESS => $image);

// 将处理后的图片保存到本地。
$ossClient->getObject($bucket, $object, $options);                           

Python

要求使用Python SDK 2.18.4及以上版本。

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
# 填写阿里云通用Region ID。
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

# 如果原图位于Bucket根目录,则直接填写图片名称source-example.jpg。如果原图不在Bucket根目录,需携带原图完整路径,例如exampledir/source-example.jpg。
key = 'source-example.jpg'

# 填写本地文件的完整路径,例如D:\\target-example.jpg。如果指定的本地文件存在会覆盖,不存在则新建。
local_file_name = 'D:\\target-example.jpg'

# 构建自定义裁剪处理参数。以原图右下角作为裁剪起点,裁减范围为900 px*900 px。
process = 'image/crop,w_900,h_900,g_se'

# 使用get_object方法,并通过process参数传入处理指令。
result = bucket.get_object_to_file(key, local_file_name, process=process)

Go

要求使用Go SDK 3.0.2及以上版本。

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func HandleError(err error) {
	fmt.Println("Error:", err)
	os.Exit(-1)
}

func main() {
	// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// 创建OSSClient实例。
	// yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
	client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
	if err != nil {
		HandleError(err)
	}

	// 指定原图所在的Bucket名称,例如examplebucket。
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}

	// 指定原图名称。如果图片不在Bucket根目录,需携带图片完整路径,例如exampledir/example.jpg。
	sourceImageName := "example.jpg"
	// 指定处理后的图片名称。
	targetImageName := "D://dest.jpg"
	// 以原图右下角作为裁剪起点,裁减范围为900 px*900 px。
	image := "image/crop,w_900,h_900,g_se"
	err = bucket.GetObjectToFile(sourceImageName, targetImageName, oss.Process(image))
	if err != nil {
		HandleError(err)
	}
}

自定义裁剪私有图片(需要绑定IMM)

以本示例中的原图为例,通过image/crop,g_face,w_200,h_200参数实现以人脸为中心裁剪范围为200 px*200 px的图片。使用g_face参数时,需要先绑定IMM Project,详情请参见参数说明

Java

要求使用3.17.4及以上版本的Java SDK。

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;

public class Demo {
    public static void main(String[] args) throws Throwable {
        // Endpoint以华东1(杭州)为例,其它Region请按实际情况填写。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填写Endpoint对应的Region信息,例如cn-hangzhou。
        String region = "cn-hangzhou";
        // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填写Bucket名称,例如examplebucket。
        String bucketName = "examplebucket";
        // 填写原图完整路径。Object完整路径中不能包含Bucket名称。
        String objectName = "example.jpg";
        // 填写自定义裁剪后保存到本地文件的完整路径,例如D:\\dest.jpg。如果指定的本地文件存在会覆盖,不存在则新建。
        String pathName = "D:\\dest.jpg";

        // 创建OSSClient实例。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // 以人脸为中心裁剪范围为200 px*200 px。
            String image = "image/crop,g_face,w_200,h_200";
            GetObjectRequest request = new GetObjectRequest(bucketName, objectName);
            request.setProcess(image);
            // 将处理后的图片保存到本地。
            // 如果未指定本地路径只填写了文件名称(例如dest.jpg),则文件默认保存到示例程序所属项目对应本地路径中。
            ossClient.getObject(request, new File("D:\\dest.jpg"));
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

PHP

要求使用PHP SDK 2.7.0及以上版本。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;

// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
$provider = new EnvironmentVariableCredentialsProvider();
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填写Bucket名称,例如examplebucket。
$bucket= "examplebucket";
// 填写原图完整路径。Object完整路径中不能包含Bucket名称。
$object = "src.jpg";
// 填写自定义裁剪后保存到本地文件的完整路径,例如D:\\dest.jpg。如果指定的本地文件存在会覆盖,不存在则新建。
// 如果未指定本地路径只填写了本地文件名称(例如dest.jpg),则文件默认保存到示例程序所属项目对应本地路径中。
$download_file = "D:\\dest.jpg";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,        
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        // 填写阿里云通用Region ID。
        "region" => "cn-hangzhou"
    );
$ossClient = new OssClient($config);

// 以人脸为中心裁剪范围为200 px*200 px。
$image = "image/crop,g_face,w_200,h_200";

$options = array(
    OssClient::OSS_FILE_DOWNLOAD => $download_file,
    OssClient::OSS_PROCESS => $image);

// 将处理后的图片保存到本地。
$ossClient->getObject($bucket, $object, $options);                           

Python

要求使用Python SDK 2.18.4及以上版本。

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
# 填写阿里云通用Region ID。
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

# 如果原图位于Bucket根目录,则直接填写图片名称source-example.jpg。如果原图不在Bucket根目录,需携带原图完整路径,例如exampledir/source-example.jpg。
key = 'source-example.jpg'

# 填写本地文件的完整路径,例如D:\\target-example.jpg。如果指定的本地文件存在会覆盖,不存在则新建。
local_file_name = 'D:\\target-example.jpg'

# 构建自定义裁剪处理参数。以人脸为中心裁剪范围为200 px*200 px
process = 'image/crop,g_face,w_200,h_200'

# 使用get_object方法,并通过process参数传入处理指令。
result = bucket.get_object_to_file(key, local_file_name, process=process)

Go

要求使用Go SDK 3.0.2及以上版本。

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func HandleError(err error) {
	fmt.Println("Error:", err)
	os.Exit(-1)
}

func main() {
	// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// 创建OSSClient实例。
	// yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
	client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
	if err != nil {
		HandleError(err)
	}

	// 指定原图所在的Bucket名称,例如examplebucket。
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}

	// 指定原图名称。如果图片不在Bucket根目录,需携带图片完整路径,例如exampledir/example.jpg。
	sourceImageName := "example.jpg"
	// 指定处理后的图片名称。
	targetImageName := "D://dest.jpg"
	// 以人脸为中心裁剪范围为200 px*200 px
	image := "image/crop,g_face,w_200,h_200"
	err = bucket.GetObjectToFile(sourceImageName, targetImageName, oss.Process(image))
	if err != nil {
		HandleError(err)
	}
}