通过自定义裁剪获取符合指定大小的OSS图片_对象存储(OSS)-阿里云帮助中心

如果您希望获取指定大小的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

从（800,50）开始，裁减至图片边界
需求及处理参数如下：
- 裁剪起点为（800,50）：crop,x_800,y_50
- 裁减至图片边界：裁剪时默认使用w和h的最大值，所以可省略w和h参数。
图片处理URL为：https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image/crop,x_800,y_50
从（800，500）开始，裁剪300 px*300 px大小的图片
需求及处理参数如下：
- 裁剪起点为（800,500）：crop,x_800,y_500
- 裁减范围300 px*300 px：w_300,h_300
图片处理URL为：https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image/crop,x_800,y_500,w_300,h_300
裁剪原图右下角900 px*900 px的范围
需求及处理参数如下：
- 裁剪起点为原图右下角：crop,g_se
- 裁减范围900 px*900 px：w_900,h_900
图片处理URL为：https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image/crop,w_900,h_900,g_se
裁剪原图右下角900 px*900 px的范围，起点为相对右下九宫格的左上顶点再位移（100,100）
需求及处理参数如下：
- 起点为原图右下角再位移（100,100）：crop,g_se,x_100,y_100
- 裁减范围900 px*900 px：w_900,h_900
图片处理URL为：https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image/crop,x_100,y_100,w_900,h_900,g_se

自定义裁剪私有图片（无需绑定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，详情请参见参数说明。