# `Image.Social`
[🔗](https://github.com/elixir-image/image/blob/v0.66.0/lib/image/social.ex#L1)

Functions to introspect standard image sizes for
various social media platforms.

# `image_usage`

```elixir
@type image_usage() :: atom()
```

The social media platform image usage.

# `platform`

```elixir
@type platform() ::
  :facebook
  | :twitter
  | :linkedin
  | :pinterest
  | :instagram
  | :tumblr
  | :youtube
  | :snapchat
  | :tiktok
```

The known social media platforms.

# `default_image_usage`

```elixir
@spec default_image_usage(platform()) :: image_usage()
```

Returns the default image type that an
image is resized to for a given platform
is no `:type` parameter is provided.

### Arguments

* `platform` is any known social platform.
  See `Image.Social.known_platforms/0`.

### Returns

* The default image type for the platform.

### Example

# `image_usages`

```elixir
@spec image_usages(platform()) :: [image_usage()]
```

Returns the image types for the given
social platform.

### Arguments

* `platform` is any known social platform.
  See `Image.Social.known_platforms/0`.

### Returns

* A list of images uses available for the
  platform.

### Examples

    iex> :profile in Image.Social.image_usages(:twitter)
    true

    iex> :thumbnail in Image.Social.image_usages(:youtube)
    true

# `known_platforms`

```elixir
@spec known_platforms() :: [platform()]
```

Returns a list of known social platforms.

### Examples

    iex> :twitter in Image.Social.known_platforms()
    true

    iex> :instagram in Image.Social.known_platforms()
    true

# `media_sizes`

Return the map of social media image
sizes.

The returned map of maps is of a standard form:

* The first key is the platform name (ie `:twitter`)
* The second key is the image type for the platform (ie `:profile`)
* The third level is optional. But if it exists it must
  have three keys: `:landscape`, `:portrait` and `:square`

The values are all of the form "WxH" where `W` is the
width in pixels and `H` is the height in pixels.

### Examples

    iex> sizes = Image.Social.media_sizes()
    iex> Map.has_key?(sizes, :twitter)
    true

    iex> sizes = Image.Social.media_sizes()
    iex> get_in(sizes, [:youtube, :thumbnail])
    "1280x720"

# `resize`

```elixir
@spec resize(Vix.Vips.Image.t(), platform(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Resize an image for a particular social
platform and usage.

This function:

* Resizes an image to the correct dimensions, including being
  image aspect aware
* Converts to the sRGB color space
* Minimises metadata (retains only Artist and Copyright)

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0`

* `platform` is the name of a known social
  media platform. See `Image.Social.known_platforms/0`.

* `options` is a keyword list of options.

### Options

* `:type` is the image type within the social
  platform for which the image should be resized. See
  `Image.Social.image_usages/1`

* All other options are passed to `Image.thumbnail!/3`.

### Returns

* `{:ok, resized_image}` or

* `{:error, reason}`

# `resize!`

```elixir
@spec resize!(Vix.Vips.Image.t(), platform(), Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Resize an image for a particular social
platform and usage.

This function:

* Resizes an image to the correct dimensions, including being
  image orientation aware
* Converts to the sRGB color space
* Minimises metadata (retains only Artist and Copyright)

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0`

* `platform` is the name of a known social
  media platform. See `Image.Social.known_platforms/0`.

* `options` is a keyword list of options.

### Options

* `:type` is the image type within the social
  platform for which the image should be resized. See
  `Image.Social.image_usages/1`

* All other options are passed to `Image.thumbnail!/3`.

## Returns

* `resized_image` or

* Raises an exception.

---

*Consult [api-reference.md](api-reference.md) for complete listing*