# perldoc > Image::Size

---
type: CommandReference
command: Image::Size
mode: perldoc
section: 
source: perldoc
---

## Quick Reference
- `imgsize("image.gif")` — return (width, height, type) from a file
- `html_imgsize("image.jpg")` — return `'width="X" height="Y"'` string
- `attr_imgsize("image.png")` — return list `('-width', X, '-height', Y)`
- `imgsize(\$buffer)` — size from an in‑memory scalar reference
- `imgsize($fh)` — size from an open filehandle
- `use Image::Size qw(:all $NO_CACHE $PCD_SCALE);` — import all functions and control variables
- `$Image::Size::GIF_BEHAVIOR = 1;` — return the first sub‑image size of an animated GIF
- `tie %Image::Size::CACHE, 'IPC::Shareable', ...;` — share the cache across processes

## Name
`Image::Size` — read the dimensions of an image in several popular formats

## Synopsis
perl
use Image::Size;

# Basic dimension retrieval
($x, $y, $type) = imgsize("globe.gif");

# HTML attribute string
use Image::Size 'html_imgsize';
$size = html_imgsize("globe.gif");   # e.g. 'width="60" height="40"'

# Named parameter list for CGI or Tk
use Image::Size 'attr_imgsize';
@attrs = attr_imgsize("globe.gif");  # e.g. ('-width', 60, '-height', 40)

# In‑memory buffer
($x, $y) = imgsize(\$img_data);

# Open filehandle
($x, $y) = imgsize($fh);
## Subroutines
- `imgsize($stream)` — Returns a three‑element list: `(width, height, type)`. On error, width and height are `undef` and the third element is an error string.
- `html_imgsize($stream)` — Returns a string `'width="X" height="Y"'` for direct insertion into HTML. Returns `undef` on failure. Compatible with HTML and XHTML.
- `attr_imgsize($stream)` — Returns a four‑element list `('-width', X, '-height', Y)` suitable for modules that use named parameter hashes (CGI, Tk). Returns `undef` on failure.

By default only `imgsize` is exported. Use `:all` to import all three, or explicitly list them. The control variables `$NO_CACHE`, `$PCD_SCALE`, `%CACHE`, and `$GIF_BEHAVIOR` can also be imported.

### Input Types
The `$stream` argument accepts:

- **string** — A file path (absolute or relative). The file is opened and read.
- **scalar reference** — A reference to a scalar containing raw image data.
- **open filehandle** — An already‑opened handle (e.g., `IO::File`). The file pointer is restored after reading.

### Recognized Formats
GIF, JPG, XBM, XPM, PPM/PGM/PBM, XV thumbnails, PNG, MNG, TIF, BMP, PSD (Adobe PhotoShop), SWF (Shockwave/Flash), CWS (compressed SWF), PCD (Kodak PhotoCD), EMF, WEBP, ICO, CUR.

If [`Image::Magick`](https://metacpan.org/pod/Image::Magick) is installed, its supported formats are also handled. The type identity returned by `imgsize` may then be the full `Image::Magick` format string rather than a 2‑3 letter abbreviation.

## Caching and Shared Memory
- **Per‑file caching** — When a filename is passed, dimensions and modification time are cached. Subsequent calls for the same file skip re‑reading unless the file has changed.
- **`$NO_CACHE`** — Importable variable. Set to a true value to disable caching entirely.  
  `$Image::Size::NO_CACHE = 1;`
- **`%CACHE`** — The internal cache hash. Import it to tie to a shared‑memory segment for multi‑process use:
  ```perl
  use Image::Size qw(%CACHE);
  use IPC::Shareable;
  tie %Image::Size::CACHE, 'IPC::Shareable', 'size', { create => 1 };
  
  See also [`IPC::MMA`](https://metacpan.org/pod/IPC::MMA) for an alternative.

## Sizing PhotoCD Images
Set the importable `$PCD_SCALE` variable to one of the following (case‑insensitive) to choose the resolution:
`base/16`, `base/4`, `base`, `base4`, `base16`, `base64`.  
Default is `'base'`. Only landscape/portrait orientation is extracted; the library does not verify that the requested resolution exists.

## Controlling GIF Behavior
`$Image::Size::GIF_BEHAVIOR` (importable) controls which dimensions are returned:

- `0` (default) — The **screen** size (the logical display area). Fastest.
- `1` — The size of the **first sub‑image**.
- `2` — The size of the **largest sub‑image** (reads the entire GIF).

## Examples
perl
# Using attr_imgsize with Tk
my $image = $widget->Photo(-file => $img_path, attr_imgsize($img_path));

# In a mod_perl handler with CGI
$r->print($Q->img({ -src => $imgpath,
                    attr_imgsize($r->lookup_uri($imgpath)->filename) }));
## See Also
- [`Image::Magick`](https://metacpan.org/pod/Image::Magick)
- [`Image::Info`](https://metacpan.org/pod/Image::Info)
- [`Graphics::Magick`](http://www.graphicsmagick.org/perl.html)
- [`IPC::Shareable`](https://metacpan.org/pod/IPC::Shareable)
- [`IPC::MMA`](https://metacpan.org/pod/IPC::MMA)