Pythonトランスフォームでメディアセットを使用する

Pythonトランスフォームでは、PDFテキストの抽出、光学文字認識（OCR）、画像のタイリング、メタデータの解析など、メディアセットを使用することができます。以下のセクションでは、ユーザーのPythonリポジトリにメディアセットを設定する方法や、Pythonトランスフォームを使用してメディアセットから読み取り、メディアセットに書き込む方法について説明します。

コードリポジトリにtransforms-mediaの依存関係を追加します。

メディアセットを操作する際には、@transformデコレーターを使用する必要があります。メディアセットの入力と出力は、transforms.mediasets.MediaSetInput および transforms.mediasets.MediaSetOutput の仕様を使用して渡すことができます。ビルド中に、これらの仕様はそれぞれ transforms.mediasets.MediaSetInputParam および transforms.mediasets.MediaSetOutputParam オブジェクトに解決されます。これらの MediaSetInputParam および MediaSetOutputParam オブジェクトは、計算関数内でメディアセットにアクセスするための手段を提供します。メディアセットの入力または出力は、他の有効なトランスフォーム入力および出力（例えば表形式のデータセットなど）と組み合わせて、任意の数を使用することができます。例えば：

Copied!
1
2
3
4
5
6
7
8
9
10
11
from transforms.api import transform
from transforms.mediasets import MediaSetInput, MediaSetOutput

# 画像を変換するためのデコレータ
@transform(
    images=MediaSetInput('/examples/images'),  # 入力画像
    output_images=MediaSetOutput('/examples/output_images')  # 出力画像
)
def translate_images(images, output_images):
    # 画像変換のためのコードをここに記述
    ...

メディアセットからの読み取り

ファイルパスまたはRIDによって、個々のメディアアイテムにアクセスできます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# transforms.apiからtransformをインポートします
from transforms.api import transform
# transforms.mediasetsからMediaSetInputとMediaSetOutputをインポートします
from transforms.mediasets import MediaSetInput, MediaSetOutput

# transformデコレータを使用して、画像の変換関数を定義します
@transform(
    # '/examples/images'のパスから画像を入力として受け取ります
    images=MediaSetInput('/examples/images'),
    # '/examples/output_images'のパスに出力画像を保存します
    output_images=MediaSetOutput('/examples/output_images')
)
def translate_images(images, output_images):
    # imagesから"path"が"image1"のメディアアイテムを取得します
    image1 = images.get_media_item_by_path("image1")
    # imagesから"ri.mio.main.media-item.123"のメディアアイテムを取得します
    image2 = images.get_media_item("ri.mio.main.media-item.123")
    ...

しかし、おそらくユーザーのメディアセット内のすべてのアイテムを変換したいと思うでしょう。これを行うためには、まず_listing_メソッドを使用してアイテムをデータフレームに取り込む必要があります。以下の例では、入力メディアセット内のすべてのアイテムをリストアップし、結果のデータフレームを表形式の出力に書き込みます：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from transforms.api import transform, Output
from transforms.mediasets import MediaSetInput
@transform(
    images=MediaSetInput('/examples/images'),
    listing_output=Output('/examples/listed_images')
)
def translate_images(ctx, images, listing_output):
    # ctxとimagesを使用してメディアアイテムのリストを生成します
    media_items_listing = images.list_media_items_by_path_with_media_reference(ctx)

    # 通常のPySpark変換をmedia_items_listingに対して行うことができます

    # データフレームのカラムの型を指定します
    column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]}
    # データフレームを出力します
    listing_output.write_dataframe(media_items_listing, column_typeclasses=column_typeclasses)

メディアセット内の複数のアイテムが特定のパスにある場合、リストに含まれるのは最新のアイテムのみです。このリストには以下のスキーマが適用されます。

+--------------------------+-----------+-------------------+
|        mediaItemRid      |    path   |  mediaReference  |
+--------------------------+-----------+-------------------+
| ri.mio.main.media-item.1 | item1.jpg |  {{reference1}}   |  # mediaItemRidはメディアアイテムのリソース識別子、pathはそのアイテムのパス、media_referenceはメディアの参照です。
| ri.mio.main.media-item.2 | item2.jpg |  {{reference2}}   |  # mediaItemRidはメディアアイテムのリソース識別子、pathはそのアイテムのパス、media_referenceはメディアの参照です。
| ri.mio.main.media-item.3 | item3.jpg |  {{reference3}}   |  # mediaItemRidはメディアアイテムのリソース識別子、pathはそのアイテムのパス、media_referenceはメディアの参照です。
+--------------------------+-----------+-------------------+

上記の例は、リストの上位3行だけを表示しています。

mediaReference 行のタイプクラスを設定することで、行をメディア参照として読み込むことができます。

get_media_item()、get_media_item_by_path()などの呼び出しは、Pythonのファイルライクなストリームオブジェクトを返します。io.open() (外部)が受け入れるすべてのオプションもサポートされています。アイテムはストリームとして読み込まれるため、ランダムアクセスはサポートされていません。

また、完全なアイテムをダウンロードすることなく、個々のメディアアイテムについてのメタデータを返すこともできます。メタデータには、画像の寸法、オーディオの長さなどの情報が含まれます。利用可能なメタデータの完全な参照については、以下の付属資料を参照してください。以下の例では、各画像のメタデータを含む行をメディアアイテムリストに追加します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
from transforms.api import transform, Output
from transforms.mediasets import MediaSetInput
from pyspark.sql import functions as F
from pyspark.sql.types import StringType
from conjure_python_client import ConjureEncoder

# transform デコレータを使用して、画像とそのメタデータをリスト化する関数を定義します。
@transform(
    images=MediaSetInput('/examples/images'),  # 入力データとして画像を指定します。
    listing_output_with_metadata=Output('/examples/listed_images_with_metadata')  # 出力データとして画像とそのメタデータのリストを指定します。
)
def translate_images(ctx, images, listing_output_with_metadata):

    # メディアアイテムのメタデータを取得する関数を定義します。
    def get_metadata(media_item_rid):
        metadata = images.get_media_item_metadata(media_item_rid)  # メディアアイテムのメタデータを取得します。
        return ConjureEncoder().default(metadata)  # メタデータをエンコードします。

    # get_metadata 関数を UDF（User Defined Function）として定義します。
    metadata_udf = F.udf(get_metadata, StringType())

    # メディアアイテムのリストを取得します。
    media_items_listing = images.list_media_items_by_path_with_media_reference(ctx)
    # メディアアイテムのリストにメタデータのカラムを追加します。
    listing_with_metadata = media_items_listing.withColumn('metadata', metadata_udf(F.col('mediaItemRid')))
    # カラムの型を定義します。
    column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]}
    # データフレームを書き出します。
    listing_output_with_metadata.write_dataframe(listing_with_metadata, column_typeclasses=column_typeclasses)

メディアセットは、標準でいくつかの組み込み変換をサポートしています。以下の付属資料でAPIおよびサポートされている変換のリストを参照してください。これらの変換への呼び出しも、Pythonファイルライクストリームオブジェクトを返します。組み込み変換を使用するには、メディアセット入力に適切なメソッドを呼び出します。例えば：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@transform(
    images=MediaSetInput('/examples/images'),  # '/examples/images'の中の画像を取り込む
    image_text_output=Output('/examples/listed_images_with_text')  # 結果を'/examples/listed_images_with_text'に出力する
)
def translate_images(ctx, images, listing_output_with_metadata):  # 画像を翻訳する関数

    def get_ocr_on_image(media_item_rid):  # 画像上のOCRを取得する関数
        return images.transform_image_to_text_ocr_output_text(media_item_rid)  # 画像からテキストをOCR出力テキストに変換する

    ocr_on_image_udf = F.udf(get_ocr_on_image, StringType())  # OCRを画像に適用するUDFを作成する

    media_items_listing = images.list_media_items_by_path_with_media_reference(ctx)  # メディアアイテムをリスト化する
    listing_with_ocr = media_items_listing.withColumn('text', ocr_on_image_udf(F.col('mediaItemRid')))  # 'text'列にOCR結果を追加する
    column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]}  # 列の型クラスを定義する
    listing_output_with_metadata.write_dataframe(listing_with_metadata, column_typeclasses=column_typeclasses)  # 結果をデータフレームとして出力する

メディアセットに書き込む

MediaSetOutput 仕様を使用することで、メディアセットを変換の出力として使用できます。通常のデータセットとは異なり、メディアセットは出力として使用される前に_すでに存在している_必要があります。これは、Foundryのファイルシステムインターフェースを使用して、メディアセットが存在するフォルダーに移動することで行えます。

アイテムをアップロードするには、出力メディアセット上で put_media_item() エンドポイントを呼び出します。このエンドポイントは、任意のファイルライクオブジェクトと、出力メディアセット内でアイテムを識別するために使用されるパスを受け入れます。以下は基本的な例です：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
from transforms.api import transform
from transforms.mediasets import MediaSetInput, MediaSetOutput

# transformデコレータを使って、画像のアップロード機能を定義します。
# MediaSetInputとMediaSetOutputを引数として受け取り、画像のアップロードとコピーを行います。
@transform(
    images=MediaSetInput('/examples/images'),  # 画像の入力パスを指定します
    output_images=MediaSetOutput('/examples/output_images')  # アップロードする画像の出力パスを指定します
)
def upload_images(images, output_images):
    # "image1.jpg"という名前の画像を取得します
    with images.get_media_item_by_path("image1.jpg") as input_image:
        # 取得した画像を"copied_image1.jpg"という名前でアップロードします
        output_images.put_media_item(input_image, "copied_image1.jpg")

一つのメディアセットから別のメディアセットへアイテムをコピーする際には、出力で fast_copy_media_item() メソッドを使用できます。これは、メディアアイテムをダウンロードして再アップロードするよりも高速で効率的なオプションです：

Copied!
1
2
3
4
5
6
7
8
9
10
11
@transform(
    # '/examples/images'パス内のメディアセットをimagesとして入力します。
    images=MediaSetInput('/examples/images'),
    # '/examples/output_images'パスにoutput_imagesとして出力します。
    output_images=MediaSetOutput('/examples/output_images')
)
def upload_images(images, output_images):
    # "image1.jpg"のパスに対応するmedia_itemのリソースIDを取得します。
    origin_media_item_rid = images.get_media_item_rid_by_path("image1.jpg")
    # imagesからorigin_media_item_ridに対応するメディアアイテムを高速にコピーし、"fast_copied_image1.jpg"という名前でoutput_imagesに保存します。
    output_images.fast_copy_media_item(images, origin_media_item_rid, "fast_copied_image1.jpg")

ユーザー定義関数（UDF）では、より高い並列性のためにアイテムをメディアセットにアップロードできます。以下の例では、入力メディアセットのPDFを組み込みのPDFからJPEGへの変換を使用してJPEGに変換し、それらのJPEGを新しい出力メディアセットにアップロードします。その後、アップロードされたJPEGのメディア参照を含む表形式のデータセットを出力します：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
from transforms.api import transform, Output
from transforms.mediasets import MediaSetInput, MediaSetOutput
from pyspark.sql import functions as F
from pyspark.sql.types import StringType

# 変換定義
@transform(
    pdfs=MediaSetInput('/examples/PDFs'),
    output_images=MediaSetOutput('/examples/JPEGs'),
    output_references=Output('/examples/JPEG listing')
)
def upload_images(ctx, pdfs, output_images, output_references):

    # JPEGアップロード関数
    def upload_jpg(media_item_rid, path):
        # PDFをJPEGに変換
        with pdfs.transform_document_to_jpg(media_item_rid, 0) as jpeg:
            # 変換したJPEGをアップロード
            response = output_images.put_media_item(jpeg, path)
        return response.media_item_rid

    # UDF関数の登録
    upload_udf = F.udf(upload_jpg, StringType())

    # PDFのリストを取得
    listed_pdfs = pdfs.list_media_items_by_path(ctx)
    # メディア参照テンプレートの取得
    media_reference_template = output_images.media_reference_template()
    # JPEGアップロードとメディア参照の作成
    uploaded_jpegs = listed_pdfs\
        .withColumn('uploaded_media_item_rid', upload_udf(F.col('mediaItemRid'), F.col('path')))\
        .select('path', 'uploaded_media_item_rid')\
        .withColumn("mediaReference", F.format_string(media_reference_template,
                                                      'uploaded_media_item_rid'))

    # 列の型クラスの定義
    column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]}
    # 結果を書き込み
    output_references.write_dataframe(uploaded_jpegs, column_typeclasses=column_typeclasses)

ファイルシステム（カタログ）データセットからのアップロード

PythonメディアセットSDKは、Palantirファイルシステム（カタログとして知られています）の従来のデータセットからメディアセットにファイルをアップロードするための組み込みツールを持っています。例えば：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# transforms.apiからtransformとInputをインポートします
from transforms.api import transform, Input
# transforms.mediasetsからMediaSetOutputをインポートします
from transforms.mediasets import MediaSetOutput

# transformデコレータを使用して、関数の入力と出力を指定します
@transform(
    pdfs_dataset=Input('/examples/PDFs'), # Inputデコレータを使用してPDFsデータセットのパスを指定します
    pdfs_media_set=MediaSetOutput('/examples/PDFs mediaset') # MediaSetOutputデコレータを使用してPDFsメディアセットのパスを指定します
)
# upload_to_media_set関数を定義します。この関数は、PDFsデータセットをPDFsメディアセットにアップロードします
def upload_to_media_set(pdfs_dataset, pdfs_media_set):
    # put_dataset_filesメソッドを使用して、PDFsデータセットのファイルをPDFsメディアセットにアップロードします
    # ignore_items_not_matching_schemaパラメータがFalseに設定されているため、スキーマに一致しないアイテムは無視されません
    pdfs_media_set.put_dataset_files(pdfs_dataset, ignore_items_not_matching_schema=False)

このトランスフォームは、データセットの全てのアイテムをメディアセットにアップロードします。もし、任意のアイテムがメディアセットのスキーマと一致しない場合（例えば、データセット内にJPEGがある場合）、ビルドは失敗します。ignore_items_not_matching_schema=True を設定することで、このような不一致は無視されます。

参照：組み込みの変換

PDFドキュメントをJPEGに変換する

PDFドキュメントの個別のページをJPEGに変換し、返します。

• 適用対象： PDFドキュメント

• 戻り値： JPEGイメージ

• パラメーター：

  • media_item_rid：変換されるメディアアイテムのRID。
  • page_number：ゼロから始まるページ番号。
  • 高さ（オプション）：出力イメージの希望高さ（ピクセル単位）。
  • 幅（オプション）：出力イメージの希望幅（ピクセル単位）。

• 例：

Copied!
1
2
# "ri.mio.main.media-item.1"という名前のPDFドキュメントをJPEG形式に変換します。0はページ番号を示します。
input_pdfs.transform_document_to_jpg("ri.mio.main.media-item.1", 0)

PDFドキュメントをPNGに変換する

PDFドキュメントの個々のページをPNGに変換し、それを返します。

• 操作対象: PDFドキュメント

• 戻り値: PNG画像

• パラメーター:

  • media_item_rid: 変換されるメディアアイテムのRID。
  • page_number: ゼロから始まるページ番号。
  • 高さ (オプション): 出力画像の希望高さ、ピクセル単位。
  • 幅 (オプション): 出力画像の希望幅、ピクセル単位。

• 例:

Copied!
1
2
# PDFファイルをPNG画像に変換する
input_pdfs.transform_document_to_png("ri.mio.main.media-item.1", 0)

最適文字認識（OCR）を用いてPDFドキュメントをページごとのテキストに変換する

ページごとにテキスト出力へOCR PDFを変換します。

• 適用対象: PDFドキュメント

• 出力: utf-8 エンコーディングの非構造化テキスト

• パラメーター:

  • media_item_rid: 変換されるメディアアイテムのRID。
  • page_number: ゼロインデックスのページ番号。
  • 言語（オプション）: 言語コード、デフォルトは ENG。

• 例:

Copied!
1
2
# 日本語のコメントを追加
input_pdfs.transform_document_to_text_ocr_output_text("ri.mio.main.media-item.1", 0)  # PDF文書をテキストに変換し、OCRの出力テキストを取得

OCRによりPDFドキュメントをページごとにhOCR XMLに変換する

ページごとにPDFをOCRでhOCR XMLに変換します。hOCRについての詳細はこちら（外部リンク）。

• 対象となるもの： PDFドキュメント

• 戻り値： utf-8エンコーディングのhOCR xml

• パラメーター：

  • media_item_rid：変換するメディアアイテムのRID。
  • page_number：0から始まるページ番号。
  • 言語（オプション）： 言語コード、デフォルトは ENG。

• 例：

Copied!
1
2
3
4
# transform_document_to_text_ocr_output_hocrは、特定のメディア項目（ここでは"ri.mio.main.media-item.1"）の特定のページ（ここでは0ページ目）を
# OCR（光学文字認識）を使用してテキストに変換し、その結果をhOCR形式で出力します。
# hOCRは、OCRの結果をXHTMLとしてマークアップするためのフォーマットです。
input_pdfs.transform_document_to_text_ocr_output_hocr("ri.mio.main.media-item.1", 0)

PDFドキュメントを変換して生のテキストを抽出する

PDFからフィールドを抽出して返します。これはOCRとは異なり、画像処理が必要ないパース方法です。

• 対象: PDFドキュメント

• 戻り値: UTF-8エンコーディングの非構造化テキスト

• パラメーター:

  • media_item_rid: 変換するメディアアイテムのRID。
  • page_number: ゼロインデックスのページ番号。

• 例:

Copied!
1
2
# "ri.mio.main.media-item.1"という名前のPDFドキュメントをテキスト形式に変換し、その結果を返す関数
input_pdfs.transform_document_to_text_raw("ri.mio.main.media-item.1", 0)

PDFドキュメントを変換してフォームフィールドを抽出する

PDF全体からすべてのフォームフィールドを抽出して返します。

• 対象: PDFドキュメント

• 戻り値: JSON

• パラメーター:

  • media_item_rid: 変換されるメディアアイテムのRID。

• 例:

Copied!
1
2
# "ri.mio.main.media-item.1"というフィールドをテキストに変換するための関数を呼び出します。
input_pdfs.transform_document_to_text_extract_field("ri.mio.main.media-item.1")

PDFドキュメントの目次を抽出するトランスフォーム

PDFからフィールドを抽出し、それを返します。

• 対象: PDFドキュメント

• 返り値: JSON

• パラメーター:

  • media_item_rid: トランスフォームするメディアアイテムのRID。

• 例:

Copied!
1
2
# "ri.mio.main.media-item.1"という名前のドキュメントをテキストに変換し、目次を抽出します。
input_pdfs.transform_document_to_text_extract_table_of_contents("ri.mio.main.media-item.1")

画像を hOCR XML に変換する

画像を hOCR XML に OCR 処理します。hOCR(外部) について詳しく知る。

• 対象: 画像

• 戻り値: JSON

• パラメーター:

  • media_item_rid: 変換されるメディアアイテムの RID。

• 例:

Copied!
1
2
# 画像からテキストに変換し、OCR出力（hOCR形式）を取得する
input_pdfs.transform_image_to_text_ocr_output_hocr("ri.mio.main.media-item.1")

画像をテキストに変換

画像をテキストに OCR 処理します。

• 対象: 画像

• 返り値: utf-8 エンコーディングの非構造化テキスト

• パラメーター:

  • media_item_rid: 変換されるメディアアイテムの RID。

• 例:

Copied!
1
2
# "ri.mio.main.media-item.1"という名前の画像をテキストに変換する関数を呼び出す
input_images.transform_image_to_text_ocr_output_text("ri.mio.main.media-item.1")