ターゲット画像の作成 (Target)

AR認識の安定性と正確性を確保するために、テクスチャが豊富で特徴点が明確、ぼやけた領域がない画像をアップロードすることを推奨します。

統合を開始する前に、以下の核心原則に注意してください：

品質優先: コントラストが低い、またはテクスチャが少ない画像のアップロードを避けてください。
競合回避: 内容が高度に類似した複数の画像をアップロードしないでください。EasyAR CRSは最も一致する結果を返しますが、類似画像は認識結果の確信度低下や予期しないジャンプを引き起こす可能性があります。

検証フェーズはEasyAR Web からの直接追加方法でターゲット画像を作成して開始できます。

ターゲット画像の作成に対応するAPIインターフェースは：API —— 新しいターゲット画像の作成です。

本番環境ではEasyAR Web からのアップロードや直接のAPI —— 新しいターゲット画像の作成呼び出しによるターゲット画像のアップロードは推奨されません。

ターゲット画像作成のベストプラクティスを参照してターゲット画像を作成することを推奨します。

Creating target image best practice

本番環境では、APIを通じた自動化された管理による3段階アプローチに従うことを強く推奨します。直接の強制アップロードは避けてください。

Step 1: 類似/競合ターゲット画像のチェック

正式な追加前に、現在の画像ライブラリに同一または極度に類似したターゲットが既に存在しないか確認します。

ツール: 類似性チェック API (similar) を使用します。
処理ロジック: APIが既存の targetId を返した場合、認識ロジックの一意性を確保するために、古い画像の上書き、削除、または競合項目の無効化が必要か評価することを推奨します。

Step 2: 認識難易度評価の事前チェック

アルゴリズムを活用して、画像が認識ターゲットとして適しているか事前に判定します。

ツール: 認識難易度スコア API (grade) を使用します。
判定基準: テストでターゲット画像の認識が非常に困難と判明した場合、素材の変更を推奨します。
参考ガイド: 詳細な評価基準は認識難易度評価の説明を参照してください。

Step 3: ターゲット画像の正式アップロード

上記2つのチェックを通過後、安全にアップロード操作を実行できます。

ツール: 新しいターゲット画像 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
サーバーエンド 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ホスト
- Your-Token → 実際のAPIキー認証トークン
- 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

Step 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--"
}

Step 2. 実行、テスト画像、鍵ファイル、およびサーバー側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);

    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();

    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: 画像ファイルの準備

Unity プロジェクト内にディレクトリを作成:

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

Assets ディレクトリ名に従って
- スクリプト CreateImageTarget.cs を作成し、以下のサンプルコードをコピー
- テスト用の画像ターゲット画像を1枚準備

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()
    {
        // 画像ファイルの読み込み（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
この4項目を修正して実行可能。準備リストで用意したパラメータを入力

Step 4: 実行

Play をクリック
Console で結果を確認:
- 成功: JSON が返される（targetId を含む）
- 失敗: HTTP / エラーメッセージ

関連トピック:

次のトピック:

ターゲット画像リストのクエリ

Table of Contents