> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-framework/modularity/image-manipulation/reference/built-in-functions/imagenew.md).

# ImageNew

## Syntax

```
ImageNew( source [, width] [, height] [, imageType] [, color] )
```

## Arguments

| Name      | Type    | Required | Default | Description                                                                                  |
| --------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------- |
| source    | any     | Yes      |         | The source for the image. Can be a file path, URL, BufferedImage, BoxImage, or empty string. |
| width     | numeric | No       |         | Width of the new image (required if creating a blank image).                                 |
| height    | numeric | No       |         | Height of the new image (required if creating a blank image).                                |
| imageType | string  | No       |         | Type of image to create (e.g., "RGB", "ARGB").                                               |
| color     | string  | No       | black   | Background color for a new blank image.                                                      |

## Returns

`BoxImage` — The newly created image object.

## Description

Creates a new image from a variety of sources:

* If `source` is a file path or URL, loads the image from that location.
* If `source` is a `BufferedImage`, wraps it in a `BoxImage`.
* If `source` is a `BoxImage`, returns a copy of it.
* If `source` is an empty string, creates a blank image using the provided `width`, `height`, `imageType`, and `color` arguments.

## Example

```boxlang
// Create from file path
img = ImageNew( "images/photo.png" );

// Create from URL
img = ImageNew( "https://example.com/image.jpg" );

// Create blank image
img = ImageNew( "", 400, 300, "RGB", "white" );

// Copy an existing BoxImage
imgCopy = ImageNew( img );
```

## Related BIFs

* ImageCopy
* ImageInfo
* ImageGetWidth
* ImageGetHeight

## Notes

* If creating a blank image, `width` and `height` are required.
* The `imageType` should match supported types (e.g., "RGB", "ARGB").
* If loading from a file or URL fails, an error is thrown.
* The default color for blank images is black unless specified.
* Hex colors may be `#RGB`, `#RRGGBB` or `#RRGGBBAA` (alpha last), with or without the leading `#`. In a BoxLang string write `##` for a literal `#`.
* A color that is neither a known name nor valid hex throws an error.
* **File handles are properly managed** - no file locking issues on Windows.
* Files can be deleted immediately after loading with `ImageNew()`.
* Images are fully loaded into memory upon creation - no lazy loading issues.
* Safe to use immediately after creation without needing to call `info()` first.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/modularity/image-manipulation/reference/built-in-functions/imagenew.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.