There are many different ways that you can use PDG to manipulate and share the frames from your projects or productions.

In this tutorial you will learn how to import external media, extract and compress image files, filter frames, convert images, arrange your frames into image montages, and turn your frames into videos.

Each part of this tutorial will step through a different way that you can manipulate images with PDG.

In the initial step of this tutorial you will learn the image manipulation workflow for importing external media into a TOP network and extracting the contents from archive files. You will use a File Pattern TOP node to import external image archives and a File Decompress TOP node to unpack the archives so that you can use the individual images in each branch of your TOP network.

In parts 1, 2, and 3 of this tutorial, you will be creating three different network branches for three different image manipulation workflows.

1. Run Houdini and start a new session.

2. Save your new scene.

   • Name your scene file imagemaniptutorial.hip.

   • Save your .hip to the \PDG_TUTORIAL_FILES folder directory.

   This will be your working project file for the rest of the tutorial.

3. In the Network Editor, navigate to the Tasks context and then dive into the topnet1 network.

4. Create a File Pattern node and rename it to import_archives.

   In the TOPs ⇥ Tab menu, you can find File Pattern in the Files category.

   

   This node will import all the external .zip image archive files located in your $HIP directory.

5. Select the import_archives node and then configure the following parameters:

   • In the Operation section, click in the Pattern parameter field and then type the following:

     $HIP/*.zip

     This will determine where on your system the node will look for the files and what file pattern (for example, like which file type) it should match.

     $HIP/ tells the node to look in your TOP network’s default working directory (as specified on the Scheduler node) for the image archive files, and the *.zip wild card tells the node to find and return all ZIP archive files.

     Tip

     To learn more about pattern wild cards, see Patterns.

   • In the Work Item section, make sure that the Split Files into Separate Items parameter is turned on.

     This tells the node to create separate work items for each matched file and store the filename data of each file in the node’s attributes.

   • Leave all the other parameters set to their default values.

   

6. Cook the import_archives node.

   Two work items appear on the import_archives node and cook. One task represents the brimstone_images_compressed.zip archive file and the other task represents the stock_pictures_compressed.zip archive file.

   

7. MMB-click on the import_archives node and look at its node info.

   Notice the Outputs that are listed. The node was able to identify and import both these image archive files because you specified a wild card file pattern in the node’s Pattern parameter field.

   

8. Create a File Decompress node and rename it to extract_images.

   In the TOPs ⇥ Tab menu, you can find File Decompress in the Files category.

   

   This node will extract the images from the archive files the import_archives node imported and then save them to disk.

9. Select the extract_images node and then configure the following parameters:

   • In the Output section, click in the Output Folder parameter field and then type the following:

     $HIP/inputs/

     This tells the node to save the extracted image files to a new folder named /inputs in your working directory.

   • Leave all the other parameters set to their default values.

   

10. Connect the input of the extract_images node to the output of the import_archives File Pattern node.

    These nodes now form the first part of your image manipulation TOP network.

11. Cook the extract_images node.

    Two work items appear on the extract_images node and cook. One task represents the Brimstone image series and the other task represents the Stock Pictures image series.

    

    Note

    Notice the purple icon next to the extract_images node in the Network Editor.

    This icon indicates that the node is dynamic.

    

    In TOPs, there are two types of nodes: static and dynamic. Static nodes can generate their work items without any inputs as they are not dependent on any upstream data. Dynamic nodes on the other hand require information from their inputs upstream to generate their work items. That is why dynamic nodes can only generate work items once they are cooking.

    To learn more about about static and dynamic TOP nodes and their significance in a TOP network, see Static vs. Dynamic.

    
    The import_archives node imports the external ZIP archive files, and the extracted_images node then extracts the images from those archives files and saves them to disk.

12. Look at the image files you extracted.

    In a file browser window, navigate to $HIP/inputs/ and inspect the images files.

    

    

13. Save your tutorial scene.

Now that all the image files you will be working with are accessible, you can now manipulate them using the workflows outlined in the following parts of the tutorial.

In part one of this tutorial you will learn the image manipulation workflow for converting images into different file formats and then compressing them into image archives. You will use an ImageMagick TOP node to convert the image files you unpacked in the initial step and a File Compress TOP node to bundle the converted images into new .zip archive files.

This process is helpful in situations where one part of your pipeline uses one image file format for frames, and another part of your pipeline uses a different image file format.

1. Create an ImageMagick node, rename it to convert_images, and then connect its input to the output of the extract_images File Decompress node.

   In the TOPs ⇥ Tab menu, you can find ImageMagick in the Images category.

   

   This node will convert all the .jpg image files you extracted from the image archives to .png image files.

2. Select the convert_images node and then configure the following parameters:

   • In the Operation parameter drop-down menu, select Convert.

     This tells the node to use the convert operation on the input images.

   • In the Operation section:

     • Set the Image Quality Percentage parameter to 100.

       This tells the node how much compression to use on the images it will convert and then output. The parameter value of 100 specifies no compression (full quality). Values less than 100 specify a percentage of compression and a reduction in quality. For example, a parameter value of 80 would compress the converted images by 20%.

     • In the Convert section, click in the Output Filename parameter field and then type the following:

       $HIP/images/{inputfilename}.png

       The {inputfilename} internal variable tells the node to name each .png image the same name as their original .jpg images.

     • Leave all the other parameters at their default values.

     

3. Create a File Compress node, rename it to export_archives, and then connect its input to the output of the convert_images ImageMagick node.

   In the TOPs ⇥ Tab menu, you can find File Compress in the Files category.

   

   This node will bundle the .png images into new .zip archive files.

4. Select the export_archives node and then configure the following parameters:

   • In the Ouput section:

     • In the Compress Method parameter drop-down menu, select ZIP.

       This tells the node to save out the new image archives as ZIP files.

     • In the Output section, click in the Output File field and then type the following:

       $HIP/archives/newarchive.`@pdg_index`.zip

       $HIP/archives tells the node to save the new archive files to a new folder named /archives in your working directory, and newarchivetells the node to prefix each archive file’s name with newarchive.

     • Leave all the other parameters at their default values.

     

5. Cook the export_archives node.

   Two work items appear on the convert_images node representing the Brimstone images and Stock Pictures series of images and then cook.

   Two work items appear on the export_archives representing each of the new image archives and then cook.

   The convert_images node converts all the .jpg image files as .png image files and saves them to disk.

   The export_archives node then compresses the Brimstone images and Stock Pictures series of .png images into two new .zip archive files and saves them to disk.

   

6. Look at the PNG images and ZIP archive files you created.

   • In a file browser window, navigate to $HIP/images/ and look at the converted images files.

     Notice that each of the converted images are named after their original filenames. This is because you used the {inputfilename} internal variable in the convert_images node’s Output Filename parameter field.

     

     

   • Navigate to $HIP/archives/ and inspect the new ZIP archive files.

     

7. Save your tutorial scene.

You can now easily share or distribute the converted images.

In part two of this tutorial you will learn the image manipulation workflow for turning a series of images into a single image mosaic or montage. You will use an ImageMagick TOP node to assemble the image files you unpacked in the initial step into two image series montages.

This process is helpful in situations where you want to review and evaluate a series of frames side-by-side in a single composite image, like when comparing the wedged frame variations of a simulation.

1. Create an ImageMagick node, rename it to make_montages, and then connect its input to the output of the extract_images File Decompress node.

   In the TOPs ⇥ Tab menu, you can find ImageMagick in the Images category.

   

   This node will take the image files you extracted from the image archives and arrange them into two montage (grid mosaic) images, one for each series of images.

2. Select the make_montages node and then configure the following parameters:

   • Select the Node tab.

     • In the Operation parameter drop-down menu, select Montage.

       This tells the node to use the montage operation on the input images.

     • Click in the Output Filename parameter field and then type the following:

       $HIP/montage/mosaic.`@pdg_index`.png

       $HIP/montage tells the node to save the montage image files to a new folder named /montage in your working directory, and mosaic tells and the node to prefix each montage file’s name with mosaic.

   • Leave all the other parameters at their default values.

   

3. Cook the make_montages node.

   Two work items appear on the node representing the Brimstone image series and the Stock Picture image series and then cook.

   

   The node assembles all the Brimstone images into one montage, all the Stock Picture images into another montage, and then saves both images to disk.

4. Look at the montage images you created.

   In a file browser window, navigate to $HIP/montage/ and inspect the montage image files.

   

   

5. Save your tutorial scene.

You can now view and compare all the images in the Brimstone and Stock Picture image series as two individual montage images.

In part three of this tutorial you will learn the image manipulation workflow for turning a series of images into a video. You will use a Filter by Expression TOP node to remove the Stock Picture images from the inputs and an FFmpeg Encode Video TOP node to turn the remaining Brimstone image series into a movie.

This process is helpful in situations where you want to review or distribute your frames as a video.

1. Create a Filter by Expression node, rename it to filter_images, and then connect its input to the output of the extract_images File Decompress node.

   In the TOPs ⇥ Tab menu, you can find Filter by Expression in the Data category.

   

   This node will use a custom expression to filter out any unwanted inputs.

2. Select the filter_images node and then configure the following parameters:

   • Click in the Filter Expression parameter field and then press ⌃ Ctrl + e to open the Edit Expression window.

   • In Edit Expression window, do the following:

     • Click in the multi-line field.

       

       Multi-line field in the Edit Expression window

     • Remove the 0 and then type the following Python expression:

       len(pdg.workItem().outputFilesForTag('file/image')) < 10

       This tells the node to remove from the inputs any series of images that has less than 10 images. For this tutorial, that series of images is the Stock Picture image series since it is comprised of only four images.

   • Click Accept.

     The Filter Expression parameter field turns green. This indicates that the parameter now contains an expression and the parameter’s expression language is currently set to HScript.

     

   • Since the expression you typed is written in Python and the Filter Expression parameter is currently set to HScript, you need to change the parameter’s expression language.

     RMB-click the Filter Expression parameter and then select Expression ▸ Change Language to Python from the context-sensitive menu that appears.

     The Filter Expression parameter field turns purple. This indicates that the parameter’s expression language is now set to Python.

     

   • Leave all the other parameters at their default values.

3. Create an FFmpeg Encode Video node, rename it to make_movie, and then connect its input to the output of the filter_images Filter by Expression node.

   In the TOPs ⇥ Tab menu, you can find FFmpeg Encode Video in the Images category.

   

   This node will take all the input images and turn them into a movie.

4. Select the make_movie node and then configure the following parameters:

   • In the Cache Mode parameter drop-down menu, select Write Files.

     This tells the node to always work on the node’s work item and never use any existing cook result files from disk.

   • In the __Output__section, click in the Output File Path parameter field and then type the following:

     $HIP/movie/brimstonevideo.mp4

     $HIP/movie tells the node to save the video file to a new folder named /movie in your working directory, and .mp4 tells the node to save out the movie as an MP4 format video file.

   • Leave all the other parameters at their default values.

   

5. Cook the make_movie node.

   One work item appears on the filter_images node representing the Brimstone series of images and then cooks.

   One work item appears on the make_movie node representing the video and then cooks.

   

   The filter_images node filters out the Stock Picture image series from the inputs.

   The make_movie node then assembles all the Brimstone images into an MP4 video file and saves it to disk.

6. Examine the work item that is generated by the make_movie node.

   • Click the work item dot on the make_movie node.

     Notice the line that appears between the work item on the make_movie node and its associated work items on upstream tasks in the network. These lines and their corresponding dot highlights indicate the connections between the work items.

   • Click the first work item dot on the extract_images node, and then click the second work item dot on the same node.

     Notice how only one work item on the extract_images node is connected to the work item on the make_movie node. This is because the filter_images node has filtered out the Stock Picture image series from the video branch of the TOP network.

7. Look at the movie you created.

   In a file browser window, navigate to $HIP/video/ and watch the MP4 video.

8. Save your tutorial scene.