PixelArray命令はSurfaceオブジェクトをラッピングし、二次配列としてピクセルを操作できるようにします。surfaceオブジェクトの横位置を配列の第一要素、縦位置を第二要素として指定し操作を行います。この命令ではslicing, row and pixel manipluation, slicing and slice assignments をサポートしている一方、加算や減産、乗算、除算などのようなインプレイス処理は行えません。
PixelArrayオブジェクトでは整数型の色情報とRGB(A)タプル型の色情報の両方を設定できますが、取得される色の情報は整数型でのみ表されます。したがって、取得したピクセルの色を判別するには、元となっているSurfaceオブジェクトでSurface.map_rgb命令を使用して整数型の色情報を把握しておく必要があります。
pxarray = pygame.PixelArray (surface)
# 画面左上のピクセルの色が青かを調べます。
if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):
...
整数型がタプル型の色情報を使ってピクセルの操作を行います。
pxarray[x][y] = 0xFF00FF pxarray[x][y] = (255, 0, 255)
slice操作を行う場合は、任意のシーケンスや他のPixelArrayオブジェクトの色情報を使用してピクセルの編集を行うこともできます。しかしながら、それらの配列範囲はPixelArrayの大きさと一致しなければなりません。
pxarray[a:b] = 0xFF00FF # 全てのピクセルの色を0xFF00FFにします。
pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # 最初のピクセル = 0xFF00FF,
# 二番目のピクセル = 0xAACCEE, ...
pxarray[a:b] = ((255, 0, 255), (170, 204, 238), ...) # 上記と同じ処理
pxarray[a:b] = ((255, 0, 255), 0xAACCEE, ...) # 上記と同じ処理
pxarray[a:b] = otherarray[x:y] # 取り出す範囲の大きさは必ず一致させてください。
下記のようにも範囲を指定しても、
pxarray[2:4][3:5] = ...
長方形の範囲を操作できるわけではないので注意してください。実際の内部の動きとしては、まず最初に2列分のピクセルデータを取り出しますが、それが既定で取り出せる列を超えているのでIndexErrorエラーが発生して処理が止まります。pythonのスライシング機能に従って正確に処理を行うと、こういった動きになってしまうのです。下記のように操作するピクセルの列を一列ずつ作成して編集作業を行ってください。:
pxarray[2][3:5] = ... pxarray[3][3:5] = ...
長方形を描写したりPixelArrayの一定範囲を取得する場合には、添え字機能を使用することもできます。添え字を使用して'subarrays'を作成することで、簡単に指定範囲のコピー画像を作成できます。
# 元surfaceの一部分を切り取ったPixelArrayオブジェクトを新規に作成します。 newarray = pxarray[2:4,3:5] otherarray = pxarray[::2,::2]
x位置とy位置を繰り返し指定して処理を行うのではなく、上記のように添え字を使用してピクセル操作を行うことによって処理を早くすることができます。
pxarray[::2,:] = (0, 0, 0) # ピクセルを2行おきに黒く塗りつぶします。
PixelArrayオブジェクトを作成すると元となるsurfaceオブジェクトがロックされます。PixelArrayオブジェクトをもう使用せず、同じスコープ内でsurfaceオブジェクトを使用するのであれば、PixelArrayオブジェクトの削除処理をちゃんと行わなければなりません。
この命令はpygameのバージョン1.8で新たに実装されました。 添え字機能はpygameのバージョン1.8.1からサポートされました。
The PixelArray wraps up a Surface and provides a direct 2D array access to its pixels using the surface its rows as first and its columns as second axis. It supports slicing, row and pixel manipluation, slicing and slice assignments while inplace operations such as addition, subtraction, multiplication, division and so forth are not allowed.
While it is possible to assign both, integer color values and RGB(A) color tuples, the PixelArray will only use integers for the color representation. Thus, checking for certain colors has to be done using the Surface.map_rgb - convert a color into a mapped color value method of the surface, the PixelArray was created for.
pxarray = pygame.PixelArray (surface)
# Check, if the first pixel at the topleft corner is blue
if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):
...
Pixels can be manipulated using integer values or color tuples.
pxarray[x][y] = 0xFF00FF pxarray[x][y] = (255, 0, 255)
If you operate on a slice, you also can use arbitrary sequences or other PixelArray objects to modify the pixels. They have to match the size of the PixelArray however.
pxarray[a:b] = 0xFF00FF # set all pixels to 0xFF00FF
pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # first pixel = 0xFF00FF,
# second pixel = 0xAACCEE, ...
pxarray[a:b] = ((255, 0, 255), (170, 204, 238), ...) # same as above
pxarray[a:b] = ((255, 0, 255), 0xAACCEE, ...) # same as above
pxarray[a:b] = otherarray[x:y] # slice sizes must match
Note, that something like
pxarray[2:4][3:5] = ...
will not cause a rectangular manipulation. Instead it will be first sliced to a two-column array, which then shall be sliced by columns once more, which will fail due an IndexError. This is caused by the slicing mechanisms in python and an absolutely correct behaviour. Create a single columned slice first, which you can manipulate then:
pxarray[2][3:5] = ... pxarray[3][3:5] = ...
If you want to make a rectangular manipulation or create a view of a part of the PixelArray, you also can use the subscript abilities. You can easily create different view by creating 'subarrays' using the subscripts.
# Create some new PixelArray objects providing a different view # of the original array/surface. newarray = pxarray[2:4,3:5] otherarray = pxarray[::2,::2]
Subscripts also can be used to do fast rectangular pixel manipulations instead of iterating over the x or y axis as above.
pxarray[::2,:] = (0, 0, 0) # Make each second column black.
During its lifetime, the PixelArray locks the surface, thus you explicitly have to delete it once its not used anymore and the surface should perform operations in the same scope.
New in pygame 1.8. Subscript support is new in pygame 1.8.1.
PixelArrayオブジェクトの元となっているSurfaceオブジェクトを取得します。
The Surface, the PixelArray was created for.
現在のPixelArrayオブジェクトの状態を基にして、Surfaceオブジェクトを新規に作成します。現在のPixelArrayオブジェクトのサイズやピクセルの配置状態などによっては、作成元のSurfaceオブジェクトとは異なったものになることもあります。
# ピクセルを上下反転させたsurfaceを新規に作成します。 sf = pxarray[:,::-1].make_surface ()
この命令はpygameのバージョン1.8.1から新たに実装されました。
Creates a new Surface from the current PixelArray. Depending on the current PixelArray the size, pixel order etc. will be different from the original Surface.
# Create a new surface flipped around the vertical axis. sf = pxarray[:,::-1].make_surface ()
PixelArrayオブジェクト上の色の中で、color引数で指定した色をrepcolor引数で指定した色に置き換えます。
色同士の違いを計算するのには、シンプルな加重ユークリッド演算を使用しています。distance引数は0.0から1.0の間で設定し、置き換える色を特定するための閾値として使用されます。閾値の値によっては、完全に一致する色ではなくほぼ同じ色を置き換えることになるので、その点も考慮してください。
この命令を実行すると、PixelArrayオブジェクトのピクセルの色は直ちに変更されます。
この命令はpygameのバージョン1.8.1で新たに実装されました。
Replaces the pixels with the passed color in the PixelArray by changing them them to the passed replacement color.
It uses a simple weighted euclidian distance formula to calculate the distance between the colors. The distance space ranges from 0.0 to 1.0 and is used as threshold for the color detection. This causes the replacement to take pixels with a similar, but not exactly identical color, into account as well.
This is an in place operation that directly affects the pixels of the PixelArray.
New in pygame 1.8.1.
指定した色に一致する全てのピクセルを抜き出して白色に変更し、一致しないピクセルは黒色に変更します。白か黒で塗りつぶされたPixelArrayオブジェクトを新規に作成し、戻り値として返します。
色同士の違いを計算するのには、シンプルな加重ユークリッド演算を使用しています。distance引数は0.0から1.0の間で設定し、置き換える色を特定するための閾値として使用されます。閾値の値によっては、完全に一致する色ではなくほぼ同じ色を抽出することになるので、その点も考慮してください。
この命令はpygameのバージョン1.8.1で新たに実装されました。
Extracts the passed color by changing all matching pixels to white, while non-matching pixels are changed to black. This returns a new PixelArray with the black/white color mask.
It uses a simple weighted euclidian distance formula to calculate the distance between the colors. The distance space ranges from 0.0 to 1.0 and is used as threshold for the color detection. This causes the extraction to take pixels with a similar, but not exactly identical color, into account as well.
New in pygame 1.8.1.
指定したPixelArrayオブジェクトとこのPixelArrayオブジェクトの内容を比較します。色の一致するピクセルを白、一致しないピクセルを黒く塗りつぶしたPixelArrayオブジェクトを新規に作成し、戻り値として返します。比較対象となる二つのPixelArrayオブジェクトは、両方とも同じビット深度と同じサイズでなければなりません。
色同士の違いを計算するのには、シンプルな加重ユークリッド演算を使用しています。distance引数は0.0から1.0の間で設定し、置き換える色を特定するための閾値として使用されます。閾値の値によっては、完全に一致する色ではなくほぼ同じ色を黒く塗りつぶすことになります。
この命令はpygameのバージョン1.8.1で新たに実装されました。
Compares the contents of the PixelArray with those from the passed PixelArray. It returns a new PixelArray with a black/white color mask that indicates the differences (white) of both arrays. Both PixelArray objects must have indentical bit depths and dimensions.
It uses a simple weighted euclidian distance formula to calculate the distance between the colors. The distance space ranges from 0.0 to 1.0 and is used as threshold for the color detection. This causes the comparision to mark pixels with a similar, but not exactly identical color, as black.
New in pygame 1.8.1.