创建目標圖像 (Target)

為確保 AR 識別的穩定性和準確性，建議您上傳紋理豐富、特徵點明顯且無模糊區域的圖像。

在開始整合前，請注意以下核心原則：

品質優先：避免上傳低對比度或紋理稀疏的圖片。
避免衝突：請勿上傳內容高度相似的多張圖像。雖然 EasyAR CRS 會回傳最匹配的結果，但相似圖會導致識別結果的置信度下降或出現意外跳轉。

開始驗證階段可以透過EasyAR Web 直接新增方法建立目標圖。

建立目標圖片對應 API 介面是：API —— 新建目標圖像。

不推薦生產上直接透過EasyAR Web 上傳或者直接呼叫API —— 新建目標圖像上傳目標圖像。

推薦參考建立目標圖最佳實踐方法建立目標圖。

建立目標圖最佳實踐

在生產環境下，我們強烈建議開發者遵循以下三步法透過 API 自動化管理目標圖，而不是直接強制上傳。

第一步：檢查相似/衝突目標圖

在正式新增之前，先檢查當前圖庫中是否已存在相同或極度相似的目標。

工具：使用相似性檢查 API (similar)。
處理邏輯：如果 API 回傳了已存在的 targetId，建議您評估是否需要覆蓋、刪除舊圖或停用衝突項，以確保識別邏輯的唯一性。

第二步：識別難度評級預檢

利用演算法預判圖像是否適合作為識別目標圖。

工具：使用識別難度評分 API (grade)。
判定標準：若測試發現目標圖極難識別，建議更換素材。
參考指南：詳細評分標準請參閱識別難度評級說明。

第三步：正式上傳目標圖

在通過上述兩項檢查後，即可安全地執行上傳操作。

工具：呼叫新建目標圖像 API。

透過 EasyAR Web 手動管理

適用於驗證階段或維護少量目標圖。Web 管理端採取「強制建立」模式，不會自動進行相似性校驗，也不校驗圖片的可識別性。

操作步驟：

登入 EasyAR 開發中心 -> 雲識別管理 -> 選擇圖庫 -> 點選管理。
在介面中點選 上傳目標圖。

Web 建立引導

關鍵參數配置：
- 名稱 (Name)：識別圖的標識符。
- 寬度 (Width)：填入圖像在物理世界中的實際尺寸。這決定了 Unity 等用戶端在識別後渲染 AR 內容的初始比例。
- 元資料 (Meta)：存放與該圖關聯的 URL、模型路徑或 JSON 配置。資料需先進行 Base64 編碼 後上傳。

參數填寫範例

使用 API 自動化建立

如需大規模管理或整合到自有後台，請使用 Web Service REST API 自動化建立。

API 介面參考建立目標圖像 API

準備清單

在發起請求前，請確保取得以下資源（詳見 API 呼叫準備清單）：

CRS AppId
API Key / Secret 或 Token
Server-end URL（目標管理入口，https 的埠 443）
測試圖片（支援 JPEG/PNG 格式，需轉為 Base64 字串）

先將本地目標圖片轉為 Base64（macOS / Linux），結果存入 image_base64.txt

base64 -i ./target.jpg | tr -d '\n' > image_base64.txt

請替換佔位符為實際參數，並運行 curl 腳本
- Your-Server-side-URL → 實際 API Host
- Your-Token → 實際的 API Key Authorization Token
- Your-CRS-AppId → 您的 appId
- demo_target → 目標名稱
- size → 目標圖片寬度(cm)

curl -X POST "https://<Your-Server-side-URL>/targets" \
  -H "Content-Type: application/json" \
  -H "Authorization: <YOUR-TOKEN>" \
  -d '{
    "appId": "<Your-CRS-AppId>",
    "image": "'"$(cat image_base64.txt)"'",
    "active": "1",
    "name": "demo_target",
    "size": "20",
    "type": "ImageTarget",
    "allowSimilar": "1"
  }'

下載 Java 範例代碼

Java Samples Download

通過 Maven 方式導入項目

Step 1. 打開相關代碼文件 CreateTarget.java

Step 2. 修改全局變量，替換你準備清單裡的認證參數

CRS AppId
API Key / API Secret
Server-end URL
IMAGE_PATH : 待上傳目標圖文件

public class CreateTarget {

    private static final String TARGET_MGMT_URL = "http://cn1.crs.easyar.com:8888";
    private static final String CRS_APPID       = "--here is your CRS AppId--";
    private static final String API_KEY         = "--here is your API Key--";
    private static final String API_SECRET      = "--here is your API Secret--";
    private static final String IMAGE_PATH      = "test_target_image.jpg";

    public String create(Auth auth, String imgPath) throws IOException{
        byte[] image = Files.readAllBytes(Paths.get(imgPath));
        if(image.length > Common.MAXIMUM_SIZE) {
            System.err.println("maximum image size is 2MB");
            System.exit(-1);
        }
        JSONObject params = new JSONObject()
                .put("name", "java-sdk-test")
                .put("image", Base64.getEncoder().encodeToString(image))
                .put("type","ImageTarget")
                .put("size", "20")
                .put("meta", "Your customized meta info");
        RequestBody requestBody = FormBody.create(MediaType.parse("application/json; charset=utf-8"),
                Auth.signParam(params, auth.getAppId(), auth.getApiKey(), auth.getApiSecret()).toString());
        Request request = new Request.Builder()
                .url(auth.getCloudURL() + "/targets")
                .post(requestBody)
                .build();
        return new OkHttpClient.Builder().readTimeout(120,TimeUnit.SECONDS).build().newCall(request).execute().body().string();
    }

    public static void main(String[] args) throws IOException {
        Auth accessInfo  =  new Auth(CRS_APPID, API_KEY, API_SECRET, TARGET_MGMT_URL);
        JSONObject createResponse = new JSONObject(new CreateTarget().create(accessInfo, IMAGE_PATH)).getJSONObject(Common.KEY_RESULT);
        System.out.println("created target: "+ createResponse.getString(Common.KEY_TARGETID));
    }
}

Step 3. 運行 Main

下載 NodeJS 範例程式碼

NodeJS Samples Download

步驟 1. 設定金鑰檔案 keys.json

CRS AppId
API Key / API Secret

{
  "appId": "--here is your appId for CRS App Instance for SDK 4--",
  "apiKey": "--here is your api key which is create from website and which has crs permission--",
  "apiSecret": "--here is your api secret which is create from website--"
}

步驟 2. 執行，指定測試圖片、金鑰檔案以及 Server-end URL

node bin/addTarget test.jpeg -t <Server-end-URL> -c keys.json

[可選] 目標圖參數程式碼

新增目標圖的邏輯，修改程式碼檔案 addTarget.js

編輯目標圖的參數，例如 meta，目標圖名稱等，對應 createTarget 方法裡傳入匿名 target 結構

var argv = require('yargs')
    .usage('Usage: $0 [image] -t [host] -c [keys]')
    .demand(1)
    .default('t', 'http://localhost:8888').alias('t', 'host')
    .default('c', 'keys.json').alias('c', 'keys')
    .help('h').alias('h', 'help')
    .epilog('copyright 2015, sightp.com')
    .argv;

var fs = require('fs');

var imageFn = argv._[0];
var host = argv.host;
var keys = JSON.parse(fs.readFileSync(argv.keys));

var farmer = require('../farmer')(host, keys.appKey, keys.appSecret);

farmer.createTarget({
    'image': fs.readFileSync(imageFn).toString('base64'),
    'name':'test2',
    'allowSimilar': '1',
    'active':'1',
    'size':'20',
    'type':'imageTarget'
})
.then(function(resp) {
    console.log(resp.result.targetId);
})
.fail(function(err) {
    console.log(err);
});

createTarget 呼叫雲端服務介面，範例程式碼在 farmer.js

function createTarget(target) {
    return Q.promise(function(resolve, reject) {
        request.post(host + '/targets')
        .send(signParams(target))
        .end(done(resolve, reject));
    });
}

新建相關代碼文件 create_target.py，修改全局變量，然後運行

pip install requests
python create_target.py

import base64, hashlib, json, time, requests

APP_ID = "your_app_id"
API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
IMAGE_PATH = "test.jpg"
API_HOST = "https://cn1-crs.easyar.com"

def sha256_hex(s: str) -> str:
    return hashlib.sha256(s.encode()).hexdigest()

image_b64 = base64.b64encode(open(IMAGE_PATH, "rb").read()).decode()
timestamp = int(time.time() * 1000)

sign_params = {
    "image": image_b64,
    "name": "demo_target",
    "size": "20",
    "meta": "",
    "type": "ImageTarget",
    "timestamp": timestamp,
    "appId": APP_ID,
    "apiKey": API_KEY
}

sign_str = "".join(f"{k}{sign_params[k]}" for k in sorted(sign_params)) + API_SECRET
print(sign_str)
signature = sha256_hex(sign_str)

body = dict(sign_params)
body["signature"] = signature

headers = {
    "Content-Type": "application/json",
    "appId": APP_ID
}

resp = requests.post(f"{API_HOST}/targets", headers=headers, json=body)
print(resp.text)

下載 Php 範例代碼

PHP Samples Download

步驟 1. 開啟入口代碼 demo.php

步驟 2. 修改全域變數，替換你準備清單裡的認證參數

CRS AppId
API Key / API Secret
Server-end URL
imageFilePath : 待上傳目標圖文件路徑

<?php
include 'EasyARClientSdkCRS.php';
$apiKey = 'API Key';
$apiSecret = 'API Secret';
$crsAppId = 'CRS AppId'
$crsCloudUrl = 'https://cn1-crs.easyar.com';
$imageFilePath = '1.jpg'

$sdk = new EasyARClientSdkCRS($apiKey, $apiSecret, $crsAppId, $crsCloudUrl);

$params = [
  'name' => 'image 1',
  'active' => '1',
  'size' => '1',
  'meta' => base64_encode('hello world'),
  'image' => base64_encode(file_get_contents($imageFilePath)),
];

$rs = $sdk->targetAdd($params);
if ($rs->statusCode == 0) {
  print_r($rs->result);
} else {
  print_r($rs);
}

步驟 3. 運行 php demo.php

Cargo.toml:

[dependencies]
reqwest = { version = "0.11", features = ["json"] }
serde_json = "1"
sha2 = "0.10"
base64 = "0.21"
tokio = { version = "1", features = ["full"] }

main.rs:

use std::{fs, collections::BTreeMap};
use sha2::{Sha256, Digest};
use base64::Engine;
use reqwest::Client;
use std::time::{SystemTime, UNIX_EPOCH};

const APP_ID: &str = "your_app_id";
const API_KEY: &str = "your_api_key";
const API_SECRET: &str = "your_api_secret";
const IMAGE_PATH: &str = "test.jpg"; // 測試圖像檔案
const API_HOST: &str = "https://cn1-crs.easyar.com";

fn sha256_hex(s: &str) -> String {
    let mut h = Sha256::new();
    h.update(s.as_bytes());
    format!("{:x}", h.finalize())
}

#[tokio::main]
async fn main() {
    let img = fs::read(IMAGE_PATH).unwrap();
    let image_b64 = base64::engine::general_purpose::STANDARD.encode(img);
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH).unwrap()
        .as_millis(); // 毫秒時間戳

    let mut sign = BTreeMap::new();
    sign.insert("image", image_b64);
    sign.insert("name", "demo_target".into());
    sign.insert("size", "20".into());
    sign.insert("meta", "".into());
    sign.insert("type", "ImageTarget".into());
    sign.insert("timestamp", timestamp.to_string());
    sign.insert("appId", APP_ID.into());
    sign.insert("apiKey", API_KEY.into());

    let mut raw = String::new();
    for (k, v) in &sign {
        raw.push_str(&format!("{}{}", k, v));
    }
    raw.push_str(API_SECRET); // 拼接API密鑰

    sign.insert("active", "1".into());
    sign.insert("signature", sha256_hex(&raw)); // 生成簽章

    let client = Client::new();
    let resp = client.post(format!("{}/targets", API_HOST))
        .header("Content-Type", "application/json")
        .header("appId", APP_ID)
        .json(&sign)
        .send().await.unwrap()
        .text().await.unwrap(); // 發送API請求

    println!("{}", resp); // 輸出回應
}

cargo run

新建相關代碼文件 main.go，修改全局變量，然後運行

go run main.go

main.go:

package main

import (
  "bytes"
  "crypto/sha256"
  "encoding/base64"
  "encoding/json"
  "fmt"
  "os"
  "sort"
  "net/http"
  "time"
)

const (
  AppID     = "your_app_id"
  ApiKey    = "your_api_key"
  ApiSecret = "your_api_secret"
  ImagePath = "test.jpg"
  ApiHost   = "https://cn1-crs.easyar.com"
)

func sha256Hex(s string) string {
  sum := sha256.Sum256([]byte(s))
  return fmt.Sprintf("%x", sum)
}

func main() {
  img, _ := os.ReadFile(ImagePath)
  imageB64 := base64.StdEncoding.EncodeToString(img)
  timestamp := time.Now().UnixMilli()

  sign := map[string]string{
    "image":     imageB64,
    "name":      "demo_target",
    "size":      "20",
    "meta":      "",
    "type":      "ImageTarget",
    "timestamp": fmt.Sprint(timestamp),
    "appId":     AppID,
    "apiKey":    ApiKey,
  }

  keys := make([]string, 0, len(sign))
  for k := range sign { keys = append(keys, k) }
  sort.Strings(keys)

  builder := ""
  for _, k := range keys {
    builder += k + sign[k]
  }
  builder += ApiSecret

  signature := sha256Hex(builder)
  sign["signature"] = signature

  body, _ := json.Marshal(sign)

  req, _ := http.NewRequest("POST", ApiHost+"/targets", bytes.NewReader(body))
  req.Header.Set("Content-Type", "application/json")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  buf := new(bytes.Buffer)
  buf.ReadFrom(resp.Body)
  fmt.Println(buf.String())
}

創建 .NET 主控台專案。

dotnet new console
dotnet run

using System;
using System.IO;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Collections.Generic;
using System.Linq;

class Program
{
    const string APP_ID = "your_app_id";
    const string API_KEY = "your_api_key";
    const string API_SECRET = "your_api_secret";
    const string IMAGE_PATH = "test.jpg";
    const string API_HOST = "https://cn1-crs.easyar.com";

    static string Sha256(string s)
    {
        return Convert.ToHexString(
            SHA256.HashData(Encoding.UTF8.GetBytes(s))
        ).ToLower();
    }

    static void Main()
    {
        var imageB64 = Convert.ToBase64String(File.ReadAllBytes(IMAGE_PATH));
        var timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();

        var sign = new SortedDictionary<string, string> {
            ["image"] = imageB64,
            ["name"] = "demo_target",
            ["size"] = "20",
            ["type"] = "ImageTarget",
            ["timestamp"] = timestamp.ToString(),
            ["appId"] = APP_ID,
            ["apiKey"] = API_KEY
        };

        var builder = string.Concat(sign.Select(p => p.Key + p.Value)) + API_SECRET;
        sign["signature"] = Sha256(builder);

        var json = JsonSerializer.Serialize(sign);
        var client = new HttpClient();

        var resp = client.PostAsync(
            API_HOST + "/targets",
            new StringContent(json, Encoding.UTF8, "application/json")
        ).Result;

        Console.WriteLine(resp.Content.ReadAsStringAsync().Result);
    }
}

運行環境
- Unity 2020 LTS 以上版本
- Scripting Backend：Mono 或 IL2CPP 均可
- API Compatibility Level：.NET Standard 2.1（推薦）

Step 1：準備圖片文件

Assets/
└── StreamingAssets/ 
|    └── target.jpg 
└── Scripts/
     └── CreateImageTarget.cs

按照 Assets 目錄名
- 建立腳本 CreateImageTarget.cs，複製下面範例程式碼
- 準備一張圖片目標測試圖

using System;
using System.IO;
using System.Text;
using UnityEngine;
using UnityEngine.Networking;
using System.Collections;

public class CreateImageTarget : MonoBehaviour
{
    [Header("Config")]
    public string apiUrl = "https://Your-Server-end-URL" + "/targets";
    public string authorizationToken = "YOUR API KEY AUTH TOKEN";
    public string imageFilePath = "target.jpg";   // StreamingAssets
    public string crsAppId = "<Your-CRS-AppId>"; 

    private void Start()
    {
        StartCoroutine(CreateTarget());
    }

    private IEnumerator CreateTarget()
    {
        // Read image file（Unity StreamingAssets）
        string fullPath = Path.Combine(Application.streamingAssetsPath, imageFilePath);

        if (!File.Exists(fullPath))
        {
            Debug.LogError($"Image file not found: {fullPath}");
            yield break;
        }

        byte[] imageBytes = File.ReadAllBytes(fullPath);
        string imageBase64 = Convert.ToBase64String(imageBytes);

        TargetRequestBody body = new TargetRequestBody
        {
            appId = crsAppId,
            image = imageBase64,
            active = "1",
            name = "unity_target",
            size = "20",
            meta = "created from unity",
            type = "ImageTarget",
            allowSimilar = "1"
        };

        string json = JsonUtility.ToJson(body);

        // UnityWebRequest
        UnityWebRequest request = new UnityWebRequest(apiUrl, "POST");
        byte[] jsonBytes = Encoding.UTF8.GetBytes(json);

        request.uploadHandler = new UploadHandlerRaw(jsonBytes);
        request.downloadHandler = new DownloadHandlerBuffer();
        request.SetRequestHeader("Content-Type", "application/json");
        request.SetRequestHeader("Authorization", authorizationToken);

        yield return request.SendWebRequest();

        if (request.result == UnityWebRequest.Result.Success)
        {
            Debug.Log("Create target success:");
            Debug.Log(request.downloadHandler.text);
        }
        else
        {
            Debug.LogError("Create target failed:");
            Debug.LogError(request.error);
            Debug.LogError(request.downloadHandler.text);
        }
    }

    [Serializable]
    private class TargetRequestBody
    {
        public string appId;
        public string image;
        public string active;
        public string name;
        public string size;
        public string meta;
        public string type;
        public string allowSimilar;
    }
}

在 Unity Editor 中：
- 建立一個空 GameObject
- 命名為 TargetUploader
- 將 CreateImageTarget 腳本拖到該物件上

Step 3：配置參數（Inspector）

在 Inspector 面板中修改。按照前面準備清單的資料修改。
- Api Url
- Authorization Token
- Image File Path : 預設 target.jpg
- CRS AppId
只需修改這四項即可運行，填入準備清單準備好的參數

Step 4：運行

點選 Play
在 Console 中檢視結果：
- 成功：返回 JSON（含 targetId）
- 失敗：HTTP / 錯誤資訊

相關主題：

下一主題：

目標圖列表查詢

Table of Contents