archived-doc-ja/reference/image/functions/getimagesize.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f8d1e172bd6d11986f0dfeb11756b90c039a39bc Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka,mumumu -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.getimagesize">
 <refnamediv>
  <refname>getimagesize</refname>
  <refpurpose>画像の大きさを取得する</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>getimagesize</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">image_info</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>getimagesize</function> 関数は、サポートする任意の形式の画像ファイルの大きさを決定し、
   ファイルの型と<literal>高さ/幅</literal>を表す文字列を返します。これらは
   <acronym>HTML</acronym> の <tag>IMG</tag>
   タグや <acronym>HTTP</acronym> の content type として使用できます。
  </para>
  <caution>
   <para>
    この関数は、<parameter>filename</parameter> が適切な画像ファイルであることを想定しています。
    画像以外のファイルを渡してもそれを画像だと判断してしまい、関数の処理は成功するでしょう。
    しかし、配列には意味のない値が含まれる場合があります。
   </para>
   <para>
    <function>getimagesize</function> を使って、そのファイルが画像であるかどうかを確かめることはできません。
    そのようなことをしたい場合は、そのために用意されたソリューション
    (<link linkend="book.fileinfo">Fileinfo</link> 拡張モジュールなど) を使いましょう。
   </para>
  </caution>
  <para>
   <function>getimagesize</function> は、
   <parameter>image_info</parameter> パラメータで追加情報を返します。
  </para>
  <note>
   <simpara>
    JPC と JP2 は異なるビット深度のコンポーネントを含むことが可能なことに
    注意してください。この場合 "bits" に対する値は、
    最も大きい深度になります。また、JP2 ファイルは <literal>複数の JPEG 2000
    コードストリーム</literal>を含む場合があります。この場合、
    <function>getimagesize</function> はファイルのルートから
    最初に遭遇するコードストリームに対する値を返します。
   </simpara>
  </note>
  <note>
   <simpara>
    アイコンに関する情報は、ビットレートが最大のアイコンから取得します。
   </simpara>
  </note>
  <note>
   <simpara>
    GIF 画像はひとつ以上のフレームからなります。
    個々のフレームは画像の一部のみを占めます。
    <function>getimagesize</function> が報告する画像のサイズは、
    (logical screen descriptor から読み込まれた) 全部のサイズです。
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
        このパラメータは、情報を取得したいファイルの名前を指定します。
        ローカルファイルへの参照、あるいは (設定で許可されているなら)
        <link linkend="wrappers">ストリーム</link>を用いたリモートファイルへの参照を指定できます。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>image_info</parameter></term>
     <listitem>
      <para>
       オプションのパラメータで、
       画像ファイルから何らかの拡張情報を引き出すことが可能です。
       現在、この変数には<acronym>JPG</acronym>ファイルについて
       異なった複数のAPPマーカーが連想配列として返されます。いくつかのプログラムは、
       これらのAPPマーカーを画像の中の埋込テキストの情報として使用します。
       最も一般的な例は、マーカーAPPl3に埋込<acronym>IPTC</acronym>
       <link xlink:href="&url.iptc;">&url.iptc;</link>情報が返されることです。
       バイナリ形式のマーカーAPP13を読むことができるよう処理するために
       <function>iptcparse</function> 関数を使用することができます。
      </para>
      <note>
       <para>
        <parameter>image_info</parameter> は、
        <acronym>JFIF</acronym> ファイルのみをサポートします。
       </para>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   最大 7 つの要素からなる配列を返します。画像の形式によっては、
   <literal>channels</literal> や <literal>bits</literal> は含まれないことがあります。
  </para>
  <para>
   0 番目および 1 番目の要素は、それぞれ画像の幅と高さを表します。
  </para>
  <note>
   <para>
    形式によっては、画像を含まないものや複数の画像を含むものがあります。
    これらの場合、<function>getimagesize</function>
    は画像のサイズを適切に決定することができません。このような場合、
    <function>getimagesize</function> が返す幅と高さはいずれもゼロとなります。
   </para>
  </note>
  <note>
   <simpara>
    <function>getimagesize</function> は、どの画像のメタデータにも依存しません。
    たとえば、Exif の <literal>Orientation</literal> フラグが、
    画像を90度か270度回転するよう設定されていた場合、
    0番目と1番目の要素は入れ替えられます。
    つまり、これらは高さと幅をそれぞれ含んでいるということです。
   </simpara>
  </note>
  <para>
   2 番目の要素は <constant>IMAGETYPE_<replaceable>*</replaceable></constant> 定数のひとつで、
   画像の形式を表します。
  </para>
  <para>
   3 番目の要素は <acronym>IMG</acronym> タグで直接利用できる文字列
   <literal>height="yyy" width="xxx"</literal>
   です。
  </para>
  <para>
   <literal>mime</literal>は画像のMIMEタイプに一致します。この情報は
   画像とともに正しい HTTP <literal>Content-type</literal>
   ヘッダを転送するために使用できます。
   <example>
    <title><function>getimagesize</function> および MIME 型</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize($filename);
$fp = fopen($filename, "rb");
if ($size && $fp) {
    header("Content-type: {$size['mime']}");
    fpassthru($fp);
    exit;
} else {
    // エラー
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <literal>channels</literal> は RGB 画像の場合に 3、CMYK 画像の場合に 4 です。
  </para>
  <para>
   <literal>bits</literal> は個々の色のビット数です。
  </para>
  <para>
   画像の形式によっては、<literal>channels</literal> や
   <literal>bits</literal> の値の存在は混乱の元です。
   たとえば、<acronym>GIF</acronym> は常に 1 ピクセルあたり
   3 チャンネルを使用しますが、グローバルカラーテーブルを使ったアニメーション GIF
   のピクセルあたりのビット数を計算することはできません。
  </para>
  <para>
   失敗した場合には &false; を返します。
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   もし <parameter>filename</parameter> のイメージにアクセスできない場合、
   <function>getimagesize</function>
   は &false; を返し、<constant>E_WARNING</constant>
   レベルのエラーを発生させます。
   読み込み時にエラーが発生した場合は、
   <function>getimagesize</function> は
   <constant>E_NOTICE</constant> レベルのエラーを発生させます。
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.2.0</entry>
       <entry>
        AVIF 画像の ビット数、チャンネル情報、幅と高さの情報(dimensions) を返すようになりました。
        これより前のバージョンでは、幅と高さの情報は <literal>0x0</literal> として報告され、ビット数とチャンネル情報は全く報告されていませんでした。
       </entry>
      </row>
      <row>
       <entry>7.1.0</entry>
       <entry>
        WebP に対応しました。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>getimagesize</function> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
echo "<img src=\"img/flag.jpg\" $attr alt=\"getimagesize() example\" />";
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>getimagesize (URL)</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize("http://www.example.com/gifs/logo.gif");

// ファイル名にスペースが含まれる場合は適切にエンコードしてください
$size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

?>
]]>
    </programlisting>
   </example>
   <example>
    <title>IPTC を返す getimagesize()</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize("testimg.jpg", $info);
if (isset($info["APP13"])) {
    $iptc = iptcparse($info["APP13"]);
    var_dump($iptc);
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.gd.notrequired;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>image_type_to_mime_type</function></member>
   <member><function>exif_imagetype</function></member>
   <member><function>exif_read_data</function></member>
   <member><function>exif_thumbnail</function></member>
   <member><function>imagesx</function></member>
   <member><function>imagesy</function></member>
  </simplelist>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->