photos — iOS のフォトライブリーへのアクセス

　photos モジュールを使うと、iOS のフォトライブラリーに保管されたメディアへのアクセスができます。

　ライブラリーへの新しい画像ファイルの追加、既にあるコンテンツの修正、そして削除もできるようになります。

　（注　最初に photos にアクセスする関数を使う際には、iPhone/iPad に許可ダイアログが表示されます。もしアクセスを拒否した場合には、ほとんどの関数は、あたかもフォトライブラリーが空であるかのような動作をします。後でアクセスを許可したくなったら、「設定」アプリの「プライバシー」で写真へのアクセスを許可することできます。アプリの許可ダイアログは一度だけ表示されます。）

始めてみましょう

　フォトライブラリー内のメディアについて作業を始めるには、通常、少なくとも一つの Asset オブジェクトを必要とします。get_assets() 関数を使用することで、次の例のように、ライブラリーから全てのデータを取得することができます：

# 最後に撮った写真を取込み、コンソールに表示

import photos
all_assets = photos.get_assets()
last_asset = all_assets[-1]
img = last_asset.get_image()
img.show()

（訳注　上記のスクリプトは、保存されている写真の数が多い場合、写真の表示に数十秒を要することがあります。all_assets[-1]の数字を変更することで、任意の写真を表示させることができます。）

　Assets オブジェクトはデータの格納場所と種類（例　image (1536 x 2048)）からなるメタデータに過ぎません。そのため、実際の画像データを得るには、上記の例のように Asset.get_image() 関数を使用しなければなりません。画像は PIL.Image オブジェクトとして返されます。代わりに ui.Image が必要な場合には、Asset.get_ui_image()を使用することになります。

　Assets は AssetCollection オブジェクトとしてまとめられています。Collections には通常のアルバムと、自動的に assets に組込まれた属性を持ったスマートアルバムの両方の形式があります。

　スマートアルバムの一種として、「スクリーンショット」アルバムがあり、 get_screenshots_album() 関数で簡単に検索することができます。次の短いスクリプトは、一番古いスクリーンショットを検索し、確認ダイアログを表示した上でライブラリーから削除します。

# 一番古いスクリーンショット画像を取得し、ライブラリーから削除

import photos
album = photos.get_screenshots_album()
screenshots = album.assets
if not screenshots:
    print('ライブラリーにスクリーンショットは無かったよ。')
else:
    oldest = screenshots[0]
    if oldest.can_delete:
        # こう書くだけで確認ダイヤログが自動的に表示されます。
        oldest.delete()
    else:
        print('一番古いスクリーンショットは消さずに残してあるよ。')

（訳注　確認ダイヤログの表示および一番古いスクリーンショットの削除は確認できていますが、print 文が実行されているか確認できていいません。（実行してもコンソールに文字が残っていない））

　編集した画像と置き換えることにより、ライブラリーの中の写真のコンテンツを修正することもできます。

　次の短いスクリプトは、「最近の項目」アルバムの最後のデータを読み込んで、グレースケール（白黒）に変換して画像を置き換えます。この編集は Photos アプリまたは Asset.revert() メソッドを使用することによって元の状態に戻すことができます：

# 最後の写真を取り込み、グレースケールに変換して差し替える

import photos
album = photos.get_recently_added_album()
last = album.assets[-1]
if last.can_edit_content:
    img = last.get_image()
    grayscale_img = img.convert('L')
    grayscale_img.save('.edit.jpg', quality=90)
    last.edit_content('.edit.jpg')
else:
    print('このデータは編集できません。')

　これまでの例では、インデックスを使って全てのデータを読み込んでいました。その他に、ユーザーに選択させるために画像のサムネイル一覧のダイアログを表示することもできます。pick_asset() 関数はデータ（または AssetCollection）のリストを取得し、選択されたデータを返します。複数選択することも可能です。引数なしで呼び出すと、「最近の項目」アルバムが表示されます：

# 複数選択可能な画像選択（イメージピッカー）ダイアログを表示し結果を表示

import photos
assets = photos.pick_asset(title='Pick some assets', multi=True)
print(assets)

関　数

photos.capture_image(camera='rear')

　標準的なカメラインターフェイスを表示し、取り込んだ PIL.Image オブジェクトの形でイメージを返します。

　デバイスにカメラが付いていない場合や、カメラインターフェイスがキャンセルされた場合には、None を返します。

　自分の写真を撮りたい場合には、引数 camera に 'front' を設定することができます。（マニュアルでのカメラ切替はいつでもできます。）

photos.get_assets(media_type='image', include_hidden=False)

　引数 media_type に指定した「image(静止画)」または「video(動画)」について、ライブラリー内にあるデータのリストを返します。デフォルトでは、隠しファイルは除いたリストになります。

photos.get_asset_with_local_id(local_id)

　引数 local_id （Asset.local_id の属性）で指定したデータをライブラリーから取得し返します。指定したデータがない場合には「IOError」が発生します。

photos.get_albums()

　フォトライブラリーの中のレギュラーアルバムのリストを返します。戻り値は AssetCollection オブジェクトのリストです。

photos.get_smart_albums()

　フォトライブラリーの中のスマートアルバムのリストを返します。戻り値は AssetCollection オブジェクトのリストです。

photos.get_moments()

　フォトライブラリーの中の全ての「モーメント」のリストを返します。「モーメント」は自動的に日付と場所でグルーピングされたデータです。戻り値は AssetCollection オブジェクトのリストです。

photos.get_favorites_album()

　「お気に入り」した全部のデータで構成されているスマートアルバムを返します。戻り値は AssetCollection オブジェクトです。

photos.get_recently_added_album()

　最近ライブラリーに追加したデータで構成されているスマートアルバムを返します。戻り値は AssetCollection オブジェクトです。

photos.get_selfies_album()

　画面側カメラで撮影したデータ（自撮り写真など）で構成されているスマートアルバムを返します。戻り値は AssetCollection オブジェクトです。

photos.get_screenshots_album()

　スクリーンショット機能で取得したデータで構成されているスマートアルバムを返します。戻り値は AssetCollection オブジェクトです。

photos.batch_delete(assets)

　フォトライブラリーから複数のデータを削除します。引数 assets は Asset オブジェクトを連ねたものでなければなりません。一つないしは複数のデータが消去不能な時には、IOError が発生し、全てのデータを削除せず残したままとします。データが削除できるかどうかについては、Asset.can_delete 属性を使って調べることができます。

photos.batch_revert(assets)

　複数のデータを、編集内容を取り消して元の状態に戻します。一つまたは複数のデータが編集不可能な場合、IOError が発生し、全てのデータを復元せずにそのままとします。データが編集できるかどうかについては、Asset.can_edit_content 属性を使って調べることができます。

photos.create_album(title)

　引数 title で与えた名前で、フォトライブラリーに新しいアルバムを生成して返します。戻り値は新しいアルバムを指し示す AssetCollection オブジェクトです。

photos.create_image_asset(image_path)

　フォトライブラリーに（例えば JPEG や PNG 形式の）引数 image_path で指定した新しい画像データを生成して返します。戻り値は新しい画像データを指し示す Asset オブジェクトです。

photos.pick_asset(assets=None, title='', multi=False)

　引数 assets で指定したサムネイル選択ダイアログを表示します。assets は Asset オブジェクトの連なり／リスト、または、単体の AssetCollection で指定します。

　引数 multi を True にした場合、ユーザーはデータを複数選択することができます。False にすると、一つのデータが選択されると画像選択ダイヤログは閉じられます。戻り値は multi が False の時は一つのデータ、True の時は Asset オブジェクトのリストになります。画像選択ダイアログがキャンセルされた場合には、None が返されます。

Asset クラス

class photos.Asset

　Asset クラスは画像とか動画といったフォトライブラリーの一つ一つのメディアごとに設定されています。Asset オブジェクトは直接初期化することはできません。get_assets() を使用するか、アルバムやスマートアルバムのAssetCollection.assets 属性にアクセスしてライブラリーから取得する必要があります。

　Asset オブジェクトはメタデータのみを含んでいます。実際の画像データを取得する場合には、Asset.get_image() と get_image_data() メソッドを使用します。

　フォトライブラリーに新しい画像データを加えるには、create_image_asset() 関数を使用し、最初にディスクに保管した画像ファイルのパスを用意します。

Asset のメソッド

Asset.get_image(original=False)

　asset の画像データを取り込みます。そして、PIL.Image オブジェクトを返します。

　デフォルトでは、画像の最新バージョンが返されます。修正や編集なしの画像を取得するには、引数 original を True に設定して呼び出します。

Asset.get_image_data(original=False)

　asset の画像データを取り込みます。そして、io.BytesIO オブジェクトとして返します。画像データをバイト文字列として取得するために io.BytesIO.getvalue() を使用することができます。

　デフォルトでは、画像の最新バージョンが返されます。修正や編集なしの画像を取得するには、引数 original を True に設定して呼び出します。

　ファイルとして画像を保存するだけであれば、このメソッドはAsset.get_image() よりも効果的です。返された io.BytesIO は画像データのファイルタイプを決めるために使用できる追加の uti 属性を持っています。

Asset.get_ui_image(size=None, crop=False)

　asset の画像データを取得し、ui.Image オブジェクトを返します。ユーザーインターフェイスに表示するためなどに使用できます。幅と高さのペアでサイズを渡すことによって、画像のよりコンパクトなバージョンを要求することが可能です。（None を渡した場合、最も大きなバージョンを取得することになります。）

　引数 crop は、引数 size で指定した画像の縦横比に合わない時の拡大縮小の方法を指定します。True を渡すと、size で指定した通りのサイズで取得します。これは例えば、サムネイル画像を生成するのに便利な方法です。

Asset.edit_content(jpeg_path)

　asset の画像コンテンツを引数 jpeg_path で指定した JPEG ファイルに置き換えます。

　asset が編集不可能な場合、IOError が発生します。Asset.can_edit_content 属性を使って、編集可能かどうか確かめることができます。

　画像ファイルは JPEG 形式でなければならないことに注意してください。他の画像フォーマットは編集コンテンツとしてはサポートされていません。（create_image_asset() を使って新しいPNGファイルやGIFファイルを作成できるにも関わらず）

　システムは編集するかどうかの確認ダイヤログを表示します。

Asset.delete()

　フォトライブラリーから asset を削除します。

　asset が削除できない場合には、IOError が発生します。asset が削除可能かどうかは、Asset.can_delete 属性を使って確認できます。

　システムは削除するかどうかの確認ダイヤログを表示します。

　複数の asset を確認ダイヤログを表示せずに削除したい場合には、batch_delete() 関数を使います。

Asset.revert()

　asset を元の状態に戻します。

　asset が編集不能な場合には、IOError が発生します。Asset.can_edit_content 属性を使えば、asset が編集可能かどうか調べることができます。

　システムは編集に関する確認ダイアログを表示します。

　複数の asset を確認ダイヤログを表示せずに元の状態に戻したい場合には、batch_revert() 関数を使います。

Asset の属性

Asset.local_id

　(読込専用、文字列)現在のデバイス上の asset の ID です。

Asset.pixel_width

　(読込専用、数値型) asset のピクセル（画素）単位の幅です。

Asset.pixel_height

　(読込専用、数値型) asset のピクセル（画素）単位の高さです。

Asset.media_type

　(読込専用、文字列) asset のメディア型です。（'image（画像）' または 'video（動画）')

Asset.media_subtypes

　(読込専用、文字列のリスト) asset のメディアのサブタイプです。(例　 'photo_screenshot（スクリーンショット）', 'photo_hdr（HDR写真）'など)

Asset.creation_date

　(読書可能、日付型) asset を生成した日付です。Asset.can_edit_properties が True の時だけ書き込めます。

Asset.modification_date

　(読書可能、日付型) asset を編集した日付です。

Asset.hidden

　(読書可能、論理型) asset をライブラリーの中で非表示にするかどうかを指定します。can_edit_properties が True の時だけ書き込めます。

Asset.favorite

　(読書可能、論理型) asset が「お気に入り」になっているかどうかを示します。can_edit_properties が True の時だけ書き込めます。

Asset.duration

　(読込専用、数値型) 動画の再生時間を秒単位で示します。（画像の場合は常にゼロになります。）

Asset.location

　(読書可能、辞書型) 写真または動画を撮影した場所の地理的な位置を示します。少なくとも「緯度」と「経度」、場合によっては高度も含む辞書型になっています。can_edit_properties が True の時だけ書き込むことができます。

Asset.can_edit_content

　(読込専用、論理型) asset のコンテンツが変更可能かどうかを示します。Asset.revert() や Asset.edit_content()で使用します。

Asset.can_edit_properties

　(読込専用、論理型) asset のメタデータが変更可能かどうかを示します。Asset.favorite, Asset.hidden, Asset.creation_date, Asset.location で使用します。

Asset.can_delete

　(読込専用、論理型) asset が Asset.delete() を使って削除可能かどうかを示します。

AssetCollection のクラス

class photos.AssetCollection

　AssetCollection オブジェクトはフォトライブラリーのコレクション、すなわちアルバムとスマートアルバムを示します。「モーメント」（日付と場所で自動的にグルーピングされた写真）もまた AssetCollection オブジェクトで示されます。

　AssetCollection は直接初期化できません。その代わりに、get_albums()、get_smart_albums()、 get_moments() 関数を使ってフォトライブラリーからコレクションを取得します。いくつかの特別なスマートアルバムは、例えば、get_screenshots_album()、get_recently_added_album()、get_selfies_album() を使って、簡単にアクセスすることもできます。

　フォトライブラリーに新しいアルバムを生成するには、create_album() 関数を使います。AssetCollection.add_assets() を使って、asset を追加することができます。（または AssetCollection.remove_assets()を使って削除することができます。）

AssetCollection のメソッド

AssetCollection.delete()

　フォトライブラリーから asset collection を削除します。asset 自体は削除されません。

　asset collection が削除不能の場合、IOError が発生します。AssetCollection.can_delete 属性で削除可能かどうか確認できます。

AssetCollection.add_assets(assets)

　asset オブジェクトのリストを、このオブジェクトが示すアルバムに追加します。

　全ての asset collection の追加が許されている訳ではありません。AssetCollection.can_add_assets 属性を使えば追加可能かどうか確認できます。

AssetCollection.add_assets(assets)

　asset オブジェクトのリストを、このオブジェクトが示すアルバムから削除します。

　全ての asset collection の削除が許されている訳ではありません。AssetCollection.can_remove_assets 属性を使えば追加可能かどうか確認できます。

AssetCollection の属性

AssetCollection.assets

　(読込専用、asset オブジェクトのリスト) asset collection を構成する asset のリストです。リスト自体を直接変更してもフォトライブラリー上の collection には影響がないことに注意が必要です。追加や削除には、それぞれ、AssetCollection.add_assets() や AssetCollection.remove_assets() を使用します。

AssetCollection.local_idb

　(読込専用、文字列)現在のデバイス上の asset collection のIDです。

AssetCollection.title

　(読書可能、文字列) asset collection の（場合によっては局所的な）タイトルです。 AssetCollection.can_rename が True の時だけ書き込むことができます。

AssetCollection.type

　(読込専用、文字列) asset collection の型です。('album', 'smart_album' または 'moment').

　AssetCollection.subtype

　(読込専用、文字列) asset collection のサブタイプです。(例えば、'favorites', 'recently_added'など)

　AssetCollection.start_date

　(読込専用、日付型) asset collection の中で一番最初の asset を作成した日付です。

　AssetCollection.end_date

　(読込専用、日付型) asset collection の中で一番最後に asset を作成した日付です。

　AssetCollection.can_delete

　(読込専用、論理型) asset collection を削除できるか否かを示します。

　AssetCollection.can_add_assets

　(読込専用、論理型) AssetCollection.add_assets() を使った asset の追加が許可されているかを示します。

　AssetCollection.can_remove_assets

　(読込専用、論理型) AssetCollection.remove_assets() を使った asset の削除が許可されているかを示します。

　AssetCollection.can_rename

　(読込専用、論理型) asset collection のタイトルを変更可能か否かを示します。

使用をお勧めしない関数

　以下の関数は以前のバージョンとの互換性確保のために使用可能としていますが、新しいコードを作成する際には使用をお勧めしません。

get_count() – カメラロールの中の画像の数を返します。
get_image(image_index=-1, original=True, raw_data=False) – カメラロールの中の画像の中から1枚を返します。get_assets() を代わりに使用して下さい。
get_metadata(image_index=-1) – カメラロールの中の画像の EXIF やその他のメタデータをディクショナリー型で返します。asset のメタデータ属性を代わりに使用して下さい。
get_thumbnail(image_index=-1) – カメラロールの中の画像の小さなサムネイル画像を返します。サムネイル画像はオリジナル画像の縦横比に関係なく、正方形になっています。Asset.get_ui_image() を代わりに使用して下さい。
pick_image(show_albums=False, include_metadata=False, original=True, raw_data=False, multi=False) – 標準的な画像選択画面を表示し、選択した画像を返します。pick_asset() を代わりに使用して下さい。
save_image(image) – カメラロールに PIL イメージまたは ui.Image を保管します。create_image_asset() を代わりに使用して下さい。

photos — iOS のフォトライブリーへのアクセス