Using The Houdini Shell Utility icp

I’m a command line guy. Anytime I need to modify or convert images in bulk, rename images or even move images when you render 5000 frames to the Desktop I reach for a shell. If a tool is not available, I just whip up a quick Bash script to do some work. Now, there is definitely no shortage of image modification or conversion utilities and applications. You may have a favorite app you always reach for or you may do it the hard way of opening up that bulky image editor to do the modifications or conversions. What does this have to do with Houdini? Well, you’ll be glad to know Houdini ships with a bunch of stand alone utilities that help with operations such as this. Today, we are going to work with the Houdini shell utility icp.

Thumbs up


Stand-alone utilities 

Houdini includes a large number of useful command-line utility programs located in the $HFS/bin folder inside the Houdini install directory. There are a bunch of them ranging from alembic utilities to displaying statistics about DOPs simulation cache files.

Today we will go over icp because it’s quite a handy and simple utility to have in the back pocket of your skinny jeans. The technical documentation says icp can take a source image, copy the image, or a portion of it, and produce an output image. There are several other things you can do like flipping the image vertically or horizontally and modifying the image in place. Like a lot of these utilities bundled with Houdini, you run them from the shell.

Let’s start with a simple example. We want to take a png image and make a jpg thumbnail of it. Instead of opening Photoshop, let’s use icp. Now, before your eye glaze over you do not need to know anything about coding. You are basically just typing in three characters followed by the name of the files. No complex code logic involved. I will also show you an example of how you would use it in a simple Bash script.

Sourcing The Houdini Utilities

So before any of this works the shell needs to know where to look for the executable files. Let me show you how this works. Open up a command prompt on Windows or Terminal on OS X. I would say Linux but if you’re on a Unix box then I assume you already know most of this.

Type the following in the command prompt or Terminal:

Command not found
Command not found error.


Most likely you got an error. As I mentioned, the icp command is not recognized in a vanilla Terminal because it doesn’t know where to find the program. There are a few ways to fix this. One is modifying your $PATH to include the bin directory. If you don’t know what that means don’t worry about it for now. The easiest way to get this working is to open up the pre-configured Command Prompt or Terminal that SideFX provides. You can find it in the Utilities folder under the Houdini install directory.

SideFX Terminal
SideFX Terminal


If you open up this Command Prompt or Terminal you will see a short message indicating that the Houdini environment has been initialized. You should now have access to all the stand alone Houdini utilities. If you try typing icp you should get some help text scroll by. We are ready to rock!

icp working
icp usage text.


Using icp

Now that we are all set, let’s start actually doing something with the command. At its most basic, you type in the command followed by a source image and a destination image.

icp inimage outimage

The command copies image data, or a portion of the image that you specify, from the from-image to the to-image. If the source image filetype differs from the target image, then the file is converted to the new filetype automatically.

As with many command line type utilities, you can pass arguments or flags that modify the how the command behaves. If you don’t supply any arguments, icp copies an entire image from the specified source to the destination.

Let’s take an png image of this beautiful BMW M3 with a cat1 on top and make a thumbnail of it as a tif filetype that is 75px x 75px.

BMW M3 with cool cat
BMW M3 with cool cat on top.


In order to accomplish this we issue the following command:

icp -w 75 -h 75 m3.png m3-thumb.tif
Creating a thumbnail with icp
Creating a thumbnail with icp


That was simple enough no? We used the -w and -h flags followed by a dimension value to specify what the output of the destination image would be. You probably guessed what the w and h stand for already (width and height, just in case 😉). Also, notice the dimension values are not followed by px or anything else. It’s just the value. We can do the equivalent by using just the -r flag to specify both width and height like so:

icp -r 75 75 m3.png m3-thumb.tif

We can also scale to a percent of the original resolution. Lets scale the image by 25%. This time we use the -s flag and again we don’t need to add the % sign.

icp -s 25 m3.png m3-thumb.tif

Notice the thumbnail is squashed. This is because we are taking a rectangular image and making a square image out of it. We can fix this by extracting a section of the source image and using that as our thumbnail. This can be accomplished using the -C flag. The -C flag is followed by the pixel dimensions x1 x2 y1 y2. I wasn’t sure at first if the (0,0) coordinate was top left or bottom left. It’s the latter.

icp -C 200 200 275 275 m3.png m3-thumb.tif
Cropping a section of the image
Cropping a section of the image. Perfect!


Simple Example using icp

Changing one image is not a big deal. The power of these small utilities comes into play when you combine them with other commands or use them in shell scripts. As an example, let’s say we have a folder full of images. Hmmm, maybe your #everyday folder. You wan to create thumbnails for them so you can upload them to social media and gain fame and stardom as an influencer. How would we do that? Doing one image at a time would be a total bummer. What we can do is create a quick Bash script to loop through the folder and run icp on the images.

for i in *.jpg
    [ -e "$i" ] || continue
    icp -s 25 "$i" thumbnail_"$i"
Looping over a directory and using icp
Looping over a directory and using icp


First thing we want to do is go through each image in the folder. We need to use a for loop construct to do this. Here I’m setting the variable i to every image name we find in the folder. Once we start using the variable, it will undergo what is called variable expansion and will hold the name of the image. Make sure you are in the directory where the images are located. Otherwise you need to specify the exact path to the images.

for i in *.jpg

The asterisk we are using is a wildcard. It is useful in many ways and commands can use wildcards to perform actions on one or more files at a time. What we are doing here is called a glob. We always want to be specific if possible. I know that all the images in the folder are of filetype jpg so the above line says match all files with names ending in .jpg. from the current directory. If we had a mix of filetypes, we could have done something like this:

for i in *

Using the asterisk alone will match everything in the directory so this is why it’s always better to be specific. Also, please keep in mind I’m simplifying a great deal hear because there are subtle pitfalls when using wildcards like this but like I always say, I leave it to reader research. For our example this works well.

The third line is a check to make sure that the files we want to loop over are actually there. The code within brackets [ -e "$i ]says it’s True if the file exists. In Bash these flags within brackets are know as primaries. This is followed by two pipes which is the or logical operator. If the file exists proceed with the icp command otherwise if there is no such file then we go back to the beginning of the loop and continue with the next file. Again, you can go crazy with error checking but it’s always a good idea to get into the practice of adding a bit of it.

[ -e "$i" ] || continue

Finally, the fourth line uses does the work. Here we simply scale down the image by a percentage amount using the -s flag we saw previously. The last section of the line may be a bit confusing so let me explain.

icp -s 25 "$i" thumbnail_"$i"

Remember we stored the file names in our variable i. Here we are feeding that variable to icp as our from-file. For our to-file we reuse the variable but we prepend the string “thumbnail_”. Therefore, we get thumbnail_originalFileName. Using variables in Bash requires the use of the $ and it is recommended you always double-quote your variables.

Many Possibilities

This is just the tip of the iceberg. You can also pipe them to other commands such as iconvert, which converts from one image type to another. If you have your environment setup correctly, you can use these utilities in more complex shell scripts for some nifty automation.

The Houdini utility commands are hidden away and don’t get much love but there are some gems to be found.

1.  That’s my car but not my cat. I don’t let my cats outside.  😀



I am a motion designer & developer based out of South Florida. When not designing or animating pixels, I wrangle some code. If all else fails, I watch Twilight Zone, I Love Lucy, or Three's Company reruns.