テクノハイウェイ株式会社

ひび割れ自動検出サービスＡＰＩ version 1.1rc

本APIを利用するアプリケーションソフトウェア、Webサイトを開発する際にはAPIキーが必要です。APIキーの発行には、別途申請が必要です。また、アプリケーションソフトウェアやドメインに対して１つだけ発行しており、同一ソフトウェア、同一ドメインに対し複数発行することは原則ありません。ご利用に際しては、サービス利用サイト（https://www.mihari.net）の情報にもとづいて、あらかじめ所定の登録手続きを完了してください。

アプリケーションソフトウェア、あるいは情報システム等から本APIを利用する際には、利用者毎に本APIの利用登録をしていただき、サインイン可能なユーザー名とパスワードをご準備いただく必要があります。

本APIは、一般的なREST APIの枠組みに従って構成されています。ご利用手順の概要を図１に示します。大きく分けて３つの工程があります。サインイン工程、検出実行工程、サインアウト工程です。それぞれの工程に対して割り当てられているリソースに対して、利用目的に応じたパラメーター設定を行ってアクセスします。

本APIの典型的な呼出し手順クライアント：サインインエンドポイントsigninへ、登録済みのユーザー名とpasswordを送信（POST）要APIキー（x-api-keyヘッダにセット）サーバー：ユーザー認証および有効性を確認後、下記情報を発行JSON形式　userurl: 以後利用する専用URL　response: トークン情報　profile: 登録情報有効性サーバー：入出力データ用URIを発行JSON形式　puturis： 画像アップロード先URI　geturis： 出力ダウンロード元URIクライアント：入力画像アップロードputurisで指定されたURIへ入力画像をPUTクライアント：結果ダウンロードgeturisで指定されたURIから結果出力をGET。1回／秒でポーリングクライアント：検出指示情報を送付エンドポイントdetectionへ検出モードおよびオプション情報を付加してリクエスト（GET）要Accessトークン(Authrizationヘッダ)要APIキー（x-api-keyヘッダ）No次処理?Yesクライアント：サインアウトエンドポイントsignoutへリクエスト（GET）要Accessトークン(Authrizationヘッダ)要APIキー（x-api-keyヘッダ）サーバー：ステータスを返送開始検出終了図１：ご利用フロー



全API共通

本APIをアプリケーション開発やWebサイトでご利用される際には、アプリケーションソフトウェア毎、あるいはドメイン毎にAPIキーが必要になります。APIキーの発行方法は、https://mihari.net にてお知らせしております。APIキーは、本APIのメソッドをリクエストする際にx-api-keyヘッダに設定することで、正当なメソッドリクエストとして処理されるようになります。

また、開発したアプリケーションやWebサイトをエンドユーザーが利用する際には、エンドユーザーによる事前登録が必要です。事前登録は、https://mihari.net の新規登録画面より行います。事前登録には、ユーザ名、メールアドレス、パスワード、決済の方法と情報の登録が必要です。

サインイン SignIn

概要

本ＡＰＩの利用を開始する際には、ユーザー名とパスワードによってサインインし、Accessトークンを取得しておく必要があります。APIによって検出機能を呼び出す場合は、リクエストヘッダにAutorizationヘッダを追加し、取得したAccessトークンをセットする必要があります。Accessトークンの有効期限は取得後４時間です。期限を過ぎた場合は、再度サインインを行い、新しいAccessトークンを取得し直してください。

サインインによってAccessトークンが取得できない場合は、ユーザーおよび決済に関する登録情報をご確認ください。

解説

  1. エンドポイント

    https://api.mihari.net/v11/users/signin

  2. メソッド

    POST

  3. ヘッダ

    リクエストヘッダ部に下記のヘッダと値を追加します。APIキーの取得には、アプリケーションごとに事前の利用申請が必要です。追加方法は、ご利用される開発環境の仕様に従ってください。

        x-api-key APIキー

  4. メッセージボディ

    ユーザー名とパスワードを以下のJSON形式でセットします。

        {"username": "ユーザー名",
     "password”: "パスワード"}

  5. オプション

    オプションはありません。

  6. 応答メッセージ

    • 成功時

      • HTTPレスポンスステータスコードは、200です。
      • メッセージ本体は、下記のようなJSONデータです。
        {
    "message": "signed-in",
    "userurl": "https://api.mihari.net/v11/users/ユーザー名/",
    "response": {
        "AccessToken": "アクセストークン文字列",
        "ExpiresIn": 14400,
        "TokenType": "Bearer"
    },
    "profile": "登録状況",
    "timestamp": "日時"
}
      • "AccessToken": Authorization用のトークン
      • "profile": プロフィールの登録状況（通常はcomplete）
      • "timestamp": 応答日時（ISO8601形式）

    • 失敗時

      • HTTPレスポンスステータスコードは、400です。
      • メッセージ本体は、下記のようなJSONデータです。
        {
    "message": "Error: エラーメッセージ",
    "timestamp": "日時"
}



サインアウト SignOut

概要

ＡＰＩ利用を終了する際に実行します。IDトークンが有効期限切れになっている場合は既にサインアウト状態になっていますので、サインアウトを呼び出す必要はありません。

解説

  1. エンドポイント

    https://api.mihari.net/v11/users/ユーザー名/signout

  2. メソッド

    GET

  3. ヘッダ

    リクエストヘッダ部に下記のヘッダと値を追加します。追加方法は、ご利用される開発環境の仕様に従ってください。

        x-api-key APIキー
    Autorization Accessトークン

  4. オプション

    オプションはありません。

  5. 応答メッセージ

    • 成功時
      • HTTPレスポンスステータスコードは、200です。
      • メッセージ本体は、下記のようなJSONデータです。summaryには、当日（today）と前日までの月次集計（monthly） の値が入ります。ただし、当日のデータは、処理と集計のタイミングのずれによって誤差が生じる可能性があります。利用料算出等精度が要求される処理には月次集計（monthly）をお使いください。
        {
    "message": "signed-out",
    "username": "ユーザー名",
    "summary": {
        "calls": "当日の検出リクエスト回数",
        "uploaded": "当日の入力画像を実際にPUTした回数",
        "size": "当日のPUTした入力画像のファイルサイズの合計",
        "units": "当日の清算ユニット数"
    },
    "timestamp": "日時"}
    • 失敗時
      • HTTPレスポンスステータスコードは、400または403です。
      • メッセージ本体は、下記のようなJSONデータです。
        {"message": "Error: エラーメッセージ",
 "username": "",
 "summary": {},
 "timestamp": "日時"}



ユーザープロファイル Profile

概要

ユーザープロファイルを取得します。

解説

  1. エンドポイント

    https://api.mihari.net/v11/users/ユーザー名/profile

  2. メソッド

    GET

  3. ヘッダ

    リクエストヘッダ部に下記のヘッダと値を追加します。追加方法は、ご利用される開発環境の仕様に従ってください。

        x-api-key APIキー
    Autorization Accessトークン

  4. オプション

    オプションはありません。

  5. 応答メッセージ

    • 成功時

      • HTTPレスポンスステータスコードは、200です。
      {
   "message": "accepted",
   "profile": {
       "status_code": "profile_get",
       "happened_at": "2021-00-00T00:00:00.000000+09:00",
       "username": "username",
       "payment_method": "",
       "unit_price": "220",
       "summary": {
           "calls": "当日の検出リクエスト回数",
           "uploaded": "当日の入力画像を実際にPUTした回数",
           "size": "当日のPUTした入力画像のファイルサイズの合計",
           "units": "当日の清算ユニット数"
       },
   "timestamp": "2021-00-00T00:00:00.000000+09:00"
}

    • 失敗時

      • HTTPレスポンスステータスコードは、内容に応じて400台または500台が返ります。



ひび割れ検出 Crack Detection

概要

現在は、検出に関する全工程を一括して行うbatchmodeのみ有効です。
検出を行う手続きでは、最初にチケットを取得し、チケットに記載された情報に従って所定の受付へ画像を預け、結果を所定の窓口で受け取る必要があります。チケット記載の情報はJSON形式で、リクエスト時に要求した回数分の入力画像のアップロード先URLと検出結果のダウンロード元URLの組等が収容されています。

解説

  1. エンドポイント

    https://api.mihari.net/v11/users/ユーザー名/detection

  2. メソッド

    GET

  3. ヘッダ

    リクエストヘッダに Authorization を追加し、サインインで取得したIDトークンをセットします。

  4. オプション

    • 名称: "crack"

      • パラメーター："batchmode"
      • 説明：検出対象の選択。動作モードをオプション指定する。現状、検出対象はcrack、オプションはbatchmodeのみ。省略不可。
      • 使用例：[エンドポイント]?crack=batchmode

    • 名称: "repeat"

      • パラメーター：検出回数
      • 説明：検出回数を整数で指定する。上限は50。省略可。省略時は１。応答メッセージ中のputuris、geturisにおいて、各々指定回数分の要素を持つリストが得られる。
      • 使用例：[エンドポイント]?crack=batchmode&repeat=3

    • 名称："threshold"

      • パラメーター：閾値
      • 説明：検出スコアの閾値を0から255までの整数で設定する。省略可。省略時は閾値1に設定。
      • 使用例：[エンドポイント]?crack=batchmode&threshold=128

    • 名称："scale"

      • パラメーター：スケール
      • 説明：ひび割れの幅や長さをミリ換算するためのスケール（縮尺）を指定する。画像の１ピクセルが被写体の何ミリにあたるかを実数で指定する。本オプションとdistanceオプションの両方とも省略した場合は、幅・長さはピクセル単位になる。負の値など不正な数値を指定した場合は無効。省略可。
      • 使用例：[エンドポイント]?crack=batchmode&scale=0.6

    • 名称："distance"

      • パラメーター：距離
      • 説明：ひび割れの幅や長さを本オプションで指定した数値と撮影画像に含まれるEXIF情報の35mm換算焦点距離とで算出させる場合に指定する。距離は、カメラから被写体までをミリメートル単位の整数で指定する。負の値や小数など不正な数値を指定した場合は無効。対象画像のEXIF情報に35mm換算焦点距離（FocalLengthIn35mmFilm フィールド）が存在しない、あるいは有効な数値でない場合は無効。scaleオプションを指定している場合、本オプションは無視する。省略可。
      • 使用例：[エンドポイント]?crack=batchmode&distance=8000

    • 名称："indicator"

      • 削除。ver.1.1では本オプションは無効。指定するとエラーになります。

    • 名称："output"

      • 削除。ver.1.1では本オプションは無効。指定するとエラーになります。

    • 名称："jpg"

      • パラメーター：描線太さ、配色、カラーバーの表示
      • 説明：元画像にひび割れ検出結果を重畳表示し、JPEGフォーマットで出力する。省略可。
        • 描線太さは、検出結果を画像上に描画する際の線の太さを変更する場合に指定する。整数でピクセル数を指定する。省略可（省略した場合は5）。
        • 配色は、ひび割れを幅によって色分けする際の色使いを指定する。省略可（省略した場合はp1）。あらかじめ用意している２種類の配色パターンを指定する場合は、p1, p2のどちらかを指定する。独自の配色を指定する場合は、p9を指定し、その後に0mmから0.05mm毎のRGB値を16進数6桁（RRGGBB）で連ねて記述する。最後尾のRGB値に対応するひび割れ幅以降は同色を用いる。
        • カラーバーの表示は、"c"を指定する。省略可（省略した場合は非表示）。カラーバーは、色に対応する数値を示しており、画像右下に表示される。
      • 使用例：[エンドポイント]?crack=batchmode&jpg=10,p2,c
        • 上記は、描線の太さ10ピクセル、配色パターンp2とし、カラーバーを表示する。
      • 使用例：[エンドポイント]?crack=batchmode&jpg=10,p90000ff00aa008800ff
        • 上記は、描線の太さ10ピクセル、配色パターンをユーザーオリジナルとし、0以上0.05mm未満を#0000ff、0.05mm以上0.10mm未満を#00aa00、0.10mm以上を#8800ffとする。

    • 名称："dxf"

      • パラメーター：ステップ値、開始値、終了値、数値分離、トリムマーク
      • 説明：ひび割れ検出結果をDXFフォーマットで出力する。省略可。
        • ステップ値は、ひび割れ幅でレイヤー分けする際の刻み幅を実数で指定する。省略不可。ステップ値が不要な場合は0を指定する。
        • 開始値は、ステップ値で刻むレイヤーの最初のひび割れ幅を実数で指定する。省略不可。0からはじめる場合は0を指定する。開始値未満の幅のひび割れは、自動生成されたレイヤーにまとめて収容される。
        • 終了値は、ステップ値で刻むレイヤーの最後のひび割れ幅を実数で指定する。省略不可。終了値以上の幅のひび割れは、１つ自動生成されたレイヤーにまとめて収容される。
        • 数値分離は、検出した形状と数値（テキスト）を別レイヤーに分ける場合に、"d"を指定する。省略可。省略した場合は、検出した形状と数値（テキスト）が含まれるレイヤーが出力される。
        • トリムマークを出力する場合は、"t"を指定する。省略した場合はトリムマーク無し。トリムマークは、元画像の四隅の位置を表す。
      • 使用例：[エンドポイント]?crack=batchmode&dxf=0.1,0.4,1.0,d,t
        • 上記は、トリムマークを含み、次のひび割れ幅の範囲で形状レイヤーと数値レイヤーが生成される。0.0mm以上0.2mm未満、0.2mm以上0.6未満、0.6以上1.0未満、1.0以上

    • 名称："sxf"

      • パラメーター：ステップ値、開始値、終了値、数値分離、トリムマーク
      • 説明：ひび割れ検出結果をSXFフォーマットで出力する。省略可。
        • ステップ値は、ひび割れ幅でレイヤー分けする際の刻み幅を実数で指定する。省略不可。ステップ値が不要な場合は0を指定する。
        • 開始値は、ステップ値で刻むレイヤーの最初のひび割れ幅を実数で指定する。省略不可。0からはじめる場合は0を指定する。開始値未満の幅のひび割れは、自動生成されたレイヤーにまとめて収容される。
        • 終了値は、ステップ値で刻むレイヤーの最後のひび割れ幅を実数で指定する。省略不可。終了値以上の幅のひび割れは、１つ自動生成されたレイヤーにまとめて収容される。
        • 数値分離は、検出した形状と数値（テキスト）を別レイヤーに分ける場合に、"d"を指定する。省略可。省略した場合は、検出した形状と数値（テキスト）が含まれるレイヤーが出力される。
        • トリムマークを出力する場合は、"t"を指定する。省略した場合はトリムマーク無し。トリムマークは、元画像の四隅の位置を表す。
      • 使用例：[エンドポイント]?crack=batchmode&sxf=t,0.1,0.4,1.0,d
        • 上記は、トリムマークを含み、次のひび割れ幅の範囲で形状レイヤーと数値レイヤーが生成される。0.0mm以上0.2mm未満、0.2mm以上0.6未満、0.6以上1.0未満、1.0以上

    • 名称："svg"

      • パラメーター：
      • 説明：ひび割れ検出結果をSVGフォーマットで出力する。省略可。出力ファイルには、各ひび割れの形状とともに幅・長さ等の数値情報が含まれる。
      • 使用例：[エンドポイント]?crack=batchmode&svg

    • 名称："csv"

      • パラメーター：ステップ値、開始値、終了値
      • 説明：検出したひび割れの幅と長さを集計し、CSVフォーマットで出力する。省略可。
        • ステップ値は、集計する際の刻み幅を実数で指定する。省略不可。ステップ値が不要な場合は0を指定する。
        • 開始値は、ステップ値で刻む最初のひび割れ幅を実数で指定する。省略不可。開始値未満の幅のひび割れは、まとめて開始値未満として集計される。
        • 終了値は、ステップ値で刻むレイヤーの最後のひび割れ幅を実数で指定する。省略不可。終了値以上の幅のひび割れは、まとめて終了値以上として集計される。
      • 使用例：[エンドポイント]?crack=batchmode&csv=0.2,0.0,3.0
        • 上記は、0mmから0.2mm刻みで3.0mmまで集計する

    • 名称："efflo"

      • パラメーター：出力方法
      • 説明：遊離石灰を検出する。省略可。
        • 出力方法は、ひび割れ検出結果の各出力ファイルに追加で含める場合は"join"を、ひび割れと遊離石灰を別々のファイルに出力する場合は"disjoin"を指定する。
      • 使用例：[エンドポイント]?efflo=join

  5. 応答メッセージ

    • 成功時

      • HTTPレスポンスステータスコードは、201です。

      • メッセージ本体は、下記のようなJSONデータです。

        {"message": "accepted",
 "body": {"puturis": [{"id": "1" "uri": "アップロード先（ファイル名含む）URI"}],
        "geturis": [
            {"id": "1", "outputs": [
                {"type": "jpg", "uri": "ダウンロード先（ファイル名含む）URI"},
                {"type": "dxf", "uri": "ダウンロード先（ファイル名含む）URI"},
                {"type": "sxf", "uri": "ダウンロード先（ファイル名含む）URI"},
                {"type": "csv", "uri": "ダウンロード先（ファイル名含む）URI"},
                {"type": "svg", "uri": "ダウンロード先（ファイル名含む）URI"},
                {"type": "efl", "uri": "ダウンロード先（ファイル名含む）URI"}
                ]
            }]
          },
　"timestamp": "日時"}

      • "message"：受理された場合は"accepted"

      • "body": 入力用画像のアップロードおよび出力結果のダウンロードに必要なURI

        • "puturis"：JOB IDと入力用画像のPUT先URIのセット
        • "geturis"：JOB IDとオプションで指定した出力タイプごとの情報セット
          • "outputs": 出力タイプと出力ファイルURIの組で構成
            ただし、typeがjpgである出力ファイルは、オプションによってひび割れ
            のみか遊離石灰も含まれる場合がある。また、typeがeflである出力ファイルは、ファイル形式はJPEGであり、遊離石灰のみが出力される。

      • "timestamp": 受け付けた日時（ISO8601形式）

    • 失敗時

      • HTTPレスポンスステータスコードは、400です。
      • メッセージ本体は、下記のようなJSONデータです。
        {"message": "Error: エラーメッセージ",
 "timestamp": "日時"}

  6. リクエストURIの例
    https://api.mihari.net/v11/users/(ユーザー名)/detection?crack=batchmode&threshold=24&scale=0.6&jpg=10,p2,c&dxf=0.2,0.1,1.0,t&svg&csv=0.2,0,1.0