MagickWand、C API

MagickWand APIは C プログラミング言語と ImageMagick 画像処理ライブラリの推奨インターフェイスです。MagickCore C API とは異なり、MagickWand は少数の不透明型のみを使用します。アクセサは重要な wand プロパティの設定と取得に使用できます。MagickWand の公開メソッドの説明をこちらで確認できます

• Magick Wand のメソッド
• Magick Wand のプロパティの設定または取得
• Magick Wand の画像メソッド
• ピクセル反復処理器のメソッド
• ピクセル Wand のメソッド
• 画像ベクトル描画
• コマンドラインインターフェイス
• Wand ビューのメソッド
• 非推奨のメソッド
• エラーと警告コード

MagickWand プログラムの作成後、次のとおりにコンパイルします

cc `MagickWand-config --cflags --cppflags` -O2 -o wand wand.c `MagickWand-config --ldflags --libs`

ImageMagick が既定のシステムパスにない場合、PKG_CONFIG_PATH 環境変数を設定します

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

MagickWand API を利用した画像のサムネイルの作成とディスクへの書き込みを実行するサンプルプログラムをこちらで確認できます

#include <stdio.h>
#include <stdlib.h>
#include <MagickWand/MagickWand.h>

int main(int argc,char **argv)
{
#define ThrowWandException(wand) \
{ \
  char \
    *description; \
 \
  ExceptionType \
    severity; \
 \
  description=MagickGetException(wand,&severity); \
  (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
  description=(char *) MagickRelinquishMemory(description); \
  exit(-1); \
}

  MagickBooleanType
    status;

  MagickWand
    *magick_wand;

  if (argc != 3)
    {
      (void) fprintf(stdout,"Usage: %s image thumbnail\n",argv[0]);
      exit(0);
    }
  /*
    Read an image.
  */
  MagickWandGenesis();
  magick_wand=NewMagickWand();
  status=MagickReadImage(magick_wand,argv[1]);
  if (status == MagickFalse)
    ThrowWandException(magick_wand);
  /*
    Turn the images into a thumbnail sequence.
  */
  MagickResetIterator(magick_wand);
  while (MagickNextImage(magick_wand) != MagickFalse)
    MagickResizeImage(magick_wand,106,80,LanczosFilter,1.0);
  /*
    Write the image then destroy it.
  */
  status=MagickWriteImages(magick_wand,argv[2],MagickTrue);
  if (status == MagickFalse)
    ThrowWandException(magick_wand);
  magick_wand=DestroyMagickWand(magick_wand);
  MagickWandTerminus();
  return(0);
}

MagickWand API を利用した画像ピクセルの取得と設定方法を示す別のプログラムをこちらで確認できます。このサンプルは画像を読み取り、シグモイド非線形コントラスト制御を適用し、ディスクに書き込みます

#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include <MagickWand/MagickWand.h>

int main(int argc,char **argv)
{
#define SigmoidalContrast(x) \
  (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)
#define ThrowWandException(wand) \
{ \
  char \
    *description; \
 \
  ExceptionType \
    severity; \
 \
  description=MagickGetException(wand,&severity); \
  (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
  description=(char *) MagickRelinquishMemory(description); \
  exit(-1); \
}

  long
    y;

  MagickBooleanType
    status;

  MagickWand
    *contrast_wand,
    *image_wand;

  PixelInfo
    pixel;

  PixelIterator
    *contrast_iterator,
    *iterator;

  PixelWand
    **contrast_pixels,
    **pixels;

  register long
    x;

  unsigned long
    width;

  if (argc != 3)
    {
      (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
      exit(0);
    }
  /*
    Read an image.
  */
  MagickWandGenesis();
  image_wand=NewMagickWand();
  status=MagickReadImage(image_wand,argv[1]);
  if (status == MagickFalse)
    ThrowWandException(image_wand);
  contrast_wand=CloneMagickWand(image_wand);
  /*
    Sigmoidal non-linearity contrast control.
  */
  iterator=NewPixelIterator(image_wand);
  contrast_iterator=NewPixelIterator(contrast_wand);
  if ((iterator == (PixelIterator *) NULL) ||
      (contrast_iterator == (PixelIterator *) NULL))
    ThrowWandException(image_wand);
  for (y=0; y < (long) MagickGetImageHeight(image_wand); y++)
  {
    pixels=PixelGetNextIteratorRow(iterator,&width);
    contrast_pixels=PixelGetNextIteratorRow(contrast_iterator,&width);
    if ((pixels == (PixelWand **) NULL) ||
        (contrast_pixels == (PixelWand **) NULL))
      break;
    for (x=0; x < (long) width; x++)
    {
      PixelGetMagickColor(pixels[x],&pixel);
      pixel.red=SigmoidalContrast(pixel.red);
      pixel.green=SigmoidalContrast(pixel.green);
      pixel.blue=SigmoidalContrast(pixel.blue);
      pixel.index=SigmoidalContrast(pixel.index);
      PixelSetPixelColor(contrast_pixels[x],&pixel);
    }
    (void) PixelSyncIterator(contrast_iterator);
  }
  if (y < (long) MagickGetImageHeight(image_wand))
    ThrowWandException(image_wand);
  contrast_iterator=DestroyPixelIterator(contrast_iterator);
  iterator=DestroyPixelIterator(iterator);
  image_wand=DestroyMagickWand(image_wand);
  /*
    Write the image then destroy it.
  */
  status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
  if (status == MagickFalse)
    ThrowWandException(image_wand);
  contrast_wand=DestroyMagickWand(contrast_wand);
  MagickWandTerminus();
  return(0);
}

wand ビューを利用してアルゴリズムを並列実行することで、デュアルまたはクアッドコアープロセッシングシステムの利点を活用して同じコントラスト向上を実現しましょう。sigmoidal-contrast.cモジュールは画像を読み込み、シグモイド非線形コントラスト制御を適用し、ディスクに書き込みます。これは以前のコントラスト向上プログラムと同じですが、今回は並列実行を行います（OpenMP サポートを使用して ImageMagick をビルドしたことを想定しています）

#include <stdio.h>
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include <MagickWand/MagickWand.h>

static MagickBooleanType SigmoidalContrast(WandView *contrast_view,
  const ssize_t y,const int thread_id,void *context)
{
#define SigmoidalContrast(x) \
  (QuantumRange*(1.0/(1+exp(10.0*(0.5-QuantumScale*x)))-0.0066928509)*1.0092503)

  PixelInfo
    pixel;

  PixelWand
    **pixels;

  RectangleInfo
    extent;

  register ssize_t
    x;

  extent=GetWandViewExtent(contrast_view);
  pixels=GetWandViewPixels(contrast_view);
  for (x=0; x < (ssize_t) extent.width; x++)
  {
    PixelGetMagickColor(pixels[x],&pixel);
    pixel.red=SigmoidalContrast(pixel.red);
    pixel.green=SigmoidalContrast(pixel.green);
    pixel.blue=SigmoidalContrast(pixel.blue);
    pixel.index=SigmoidalContrast(pixel.index);
    PixelSetPixelColor(pixels[x],&pixel);
  }
  return(MagickTrue);
}

int main(int argc,char **argv)
{
#define ThrowWandException(wand) \
{ \
  char \
    *description; \
 \
  ExceptionType \
    severity; \
 \
  description=MagickGetException(wand,&severity); \
  (void) fprintf(stderr,"%s %s %lu %s\n",GetMagickModule(),description); \
  description=(char *) MagickRelinquishMemory(description); \
  exit(-1); \
}

  MagickBooleanType
    status;

  MagickWand
    *contrast_wand;

  PixelInfo
    pixel;

  WandView
    *contrast_view;

  if (argc != 3)
    {
      (void) fprintf(stdout,"Usage: %s image sigmoidal-image\n",argv[0]);
      exit(0);
    }
  /*
    Read an image.
  */
  MagickWandGenesis();
  contrast_wand=NewMagickWand();
  status=MagickReadImage(contrast_wand,argv[1]);
  if (status == MagickFalse)
    ThrowWandException(contrast_wand);
  /*
    Sigmoidal non-linearity contrast control.
  */
  contrast_view=NewWandView(contrast_wand);
  if (contrast_view == (WandView *) NULL)
    ThrowWandException(contrast_wand);
  status=UpdateWandViewIterator(contrast_view,SigmoidalContrast,(void *) NULL);
  if (status == MagickFalse)
    ThrowWandException(contrast_wand);
  contrast_view=DestroyWandView(contrast_view);
  /*
    Write the image then destroy it.
  */
  status=MagickWriteImages(contrast_wand,argv[2],MagickTrue);
  if (status == MagickFalse)
    ThrowWandException(contrast_wand);
  contrast_wand=DestroyMagickWand(contrast_wand);
  MagickWandTerminus();
  return(0);
}

MagickWandTerminus()は ImageMagick ライブラリの関数であり、ImageMagick を使用するアプリケーションを終了する際にリソースをクリーンアップして解放するために使用されます。この関数はシャットダウンプロセスの最中にアプリケーションのプライマリの処理で呼び出す必要があります。この関数は、ImageMagick 関数を使用するすべての処理が終了した後にのみ呼び出すことが非常に重要です

ImageMagick は内部的に OpenMP（並列プログラミングの手法）を利用する場合があります。そのため、MagickWandTerminus()を呼び出す前に、ImageMagick に対するすべての関数呼び出しが完了していることを確認することが重要です。これにより、OpenMP ワーカースレッドによるこの終了関数によって破棄されるリソースへのアクセスに関する問題を防ぎます

OpenMP が使用されている場合（バージョン 5.0 以降）、OpenMP 実装自体がワーカースレッドの開始と停止、リソースの割り当てと解放を独自のメソッドを使用して処理します。つまり、MagickWandTerminus()を呼び出した後でも、一部の OpenMP リソースとワーカースレッドは割り当てられたままになる場合があります。これを解消するには、omp_pause_resource_all(omp_pause_hard)関数を呼び出します。この関数は OpenMP バージョン 5.0 で導入され、OpenMP によって割り当てられたリソース（スレッドやスレッド固有のメモリーなど）がすべて解放されます。MagickWandTerminus()の実行が完了した後にこの関数を呼び出すことをお勧めします

C 言語の MagickWand の例は、ImageMagick MagickWand API の使用方法を示します。各例はヘッダー付きの C 関数として提示されるため、ファイルにコピーし、独自の C プロジェクトに含めることができます。