Getting started

Most users probably want to start with the Images.jl package, which bundles much (but not all) of the functionality in JuliaImages.

Installation

Images (and possibly some additional packages) may be all you need to manipulate images programmatically. You can install Images.jl via the package manager,

(v1.0) pkg> add Images

Loading your first image

If this is your first time working with images in julia, it's likely that you'll need to install some image IO backends to load the images. The current available backends for image files are:

• ImageMagick.jl covers most image formats and has extra functionality. This can be your first choice if you don't have a preference.
• QuartzImageIO.jl exposes macOS's native image IO functionality to Julia. In some cases it's faster than ImageMagick, but it might not cover all your needs.
• ImageIO.jl is a new image IO backend (requires julia >=v"1.3") that provides an optimized performance for PNG files. Check benchmark here
• OMETIFF.jl supports OME-TIFF files. If you don't know what it is, then it is likely that you don't need this package.

These backends aren't exclusive to each other, so if you're a macOS user, you can install all these backends. And in most cases, you don't need to directly interact with these backends, instead, we use the save and load provided by the FileIO.jl frontend. If you've installed multiple backends then FileIO will choose the most appropriate backend according to your file format. For example, if available ImageIO is used to load PNG files.

Adding these gives you a basic image IO setup:

(v1.0) pkg> add FileIO ImageMagick ImageIO

and to load an image, you can use

using Images, FileIO
# specify the path to your local image file
img_path = "/path/to/image.png"
img = load(img_path)

To save an image, you can just use save(img_path, img), where save is also provided by FileIO.

When testing ideas or just following along with the documentation, it can be useful to have some images to work with. The TestImages.jl package bundles several "standard" images for you.

(v1.0) pkg> add TestImages

To load one of the images from this package, say

using TestImages
# backends such as ImageMagick are required
img = testimage("mandrill")

Displaying images

When working with images, it's obviously helpful to be able to look at them. If you use Julia through Juno or IJulia, images should display automatically:

Currently there're five julia packages can be used to display an image:

• ImageShow is used to support image display in Juno and IJulia. This happens automatically if you are using Images.
• ImageInTerminal is used to support image display in terminal.
• ImageView is an image display GUI. (For OSX and Windows platforms, Julia at least v1.3 is required)
• Plots maintained by JuliaPlots is a general plotting package that support image display.
• Makie is also maintained by JuliaPlots but provides rich interactive functionality.

To visualize multiple images in one frame, you can create a bigger image from multiple image sources with mosaicview, which is an enhanced version of cats.

img1 = testimage("mandrill") # 512*512 RGB image
img2 = testimage("blobs") # 254*256 Gray image
mosaicview(img1, img2; nrow=1)

img = testimage("mri-stack") # 226×186×27 Gray image
mosaicview(img; fillvalue=0.5, npad=2, ncol=7, rowmajor=true)

Troubleshooting

Reading and writing images, as well as graphical display, involve interactions with external software libraries; occasionally, the installation of these libraries goes badly. Fortunately, the artifact system shipped since Julia 1.3 has made this process much more reliable, so if you're experiencing any installation trouble, please try with Julia 1.3 or higher.

This documentation is generated with the following environment setup. While reading the documentation, if you encounter any errors or if the outputs in your local machine differ from the documentation, you could first check the Julia and package versions you're using. If the error or inconsistency still exists, please file an issue for that; it helps us improve the documentation.

julia> using Pkg, Dates
julia> today()2023-08-02
julia> versioninfo()Julia Version 1.9.2
Commit e4ee485e909 (2023-07-05 09:39 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 2 × Intel(R) Xeon(R) CPU E5-2673 v4 @ 2.30GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-14.0.6 (ORCJIT, broadwell)
  Threads: 1 on 2 virtual cores
julia> Pkg.status()Status `~/work/juliaimages.github.io/juliaimages.github.io/Project.toml`
  [39de3d68] AxisArrays v0.4.7
⌅ [3da002f7] ColorTypes v0.10.12
  [5ae59095] Colors v0.12.10
  [150eb455] CoordinateTransformations v0.6.3
⌅ [311a05b2] DemoCards v0.4.11
  [b4f34e82] Distances v0.10.9
  [e30172f5] Documenter v0.27.25
  [5789e2e9] FileIO v1.16.1
  [53c48c17] FixedPointNumbers v0.8.4
⌃ [2803e5a7] ImageAxes v0.6.9
⌃ [cbc4b850] ImageBinarization v0.2.7
⌃ [f332f351] ImageContrastAdjustment v0.3.7
⌅ [a09fc81d] ImageCore v0.8.22
  [4381153b] ImageDraw v0.2.6
⌃ [2b14c160] ImageEdgeDetection v0.1.4
  [92ff4b2b] ImageFeatures v0.5.1
⌅ [6a3955dd] ImageFiltering v0.6.21
  [6218d12a] ImageMagick v1.3.0
⌃ [bc367c6b] ImageMetadata v0.9.5
⌅ [787d08f9] ImageMorphology v0.2.11
⌃ [80713f31] ImageSegmentation v1.5.1
⌅ [4e3cecfd] ImageShow v0.2.3
⌅ [02fcd773] ImageTransformations v0.8.13
⌅ [916415d5] Images v0.23.3
⌅ [9b13fd28] IndirectArrays v0.5.1
  [dbb5928d] MappedArrays v0.4.2
  [e94cdb99] MosaicViews v0.3.4
⌅ [81d43f40] Noise v0.2.2
  [6fe1bfb0] OffsetArrays v1.12.10
  [5432bcbf] PaddedViews v0.5.12
  [91a5bcdd] Plots v1.38.17
  [6038ab10] Rotations v1.5.1
  [699a6c99] SimpleTraits v0.9.4
  [5e47fb64] TestImages v1.8.0
  [1986cc42] Unitful v1.16.1
Info Packages marked with ⌃ and ⌅ have new versions available, but those with ⌅ are restricted by compatibility constraints from upgrading. To see why use `status --outdated`