Previous:File Output Options   Main Index   Next:Scene Parsing Options

CPU Utilization Histogram

The CPU utilization histogram is a way of finding out where POV-Ray is spending its rendering time, as well as an interesting way of generating heightfields. The histogram splits up the screen into a rectangular grid of blocks. As POV-Ray renders the image, it calculates the amount of time it spends rendering each pixel and then adds this time to the total rendering time for each grid block. When the rendering is complete, the histogram is a file which represents how much time was spent computing the pixels in each grid block.

Not all versions of POV-Ray allow the creation of histograms. The histogram output is dependent on the file type and the system that POV-Ray is being run on.

File Type


Set histogram type to y (Turn off if type is 'X')


Same as Histogram_Type=y

The histogram output file type is nearly the same as that used for the image output file types in "Output File Type". The available histogram file types are as follows.


Comma separated values (CSV) often used in spreadsheets


New PNG (portable network graphics) format grayscale


Unix PPM format


System-specific such as Mac Pict or Windows BMP


Uncompressed Targa-24 format (TGA)


No histogram file output is generated

Note that +HTC does not generate a compressed Targa-24 format output file but rather a text file with a comma-separated list of the time spent in each grid block, in left-to-right and top-to bottom order. The units of time output to the CSV file are system dependent. See the system specific documentation for further details on the time units in CSV files.

The Targa and PPM format files are in the POV heightfield format (see "Height Field"), so the histogram information is stored in both the red and green parts of the image, which makes it unsuitable for viewing. When used as a height field, lower values indicate less time spent calculating the pixels in that block, while higher indicate more time spent in that block.

PNG format images are stored as grayscale images and are useful for both viewing the histogram data as well as for use as a heightfield. In PNG files, the darker (lower) areas indicate less time spent in that grid block, while the brighter (higher) areas indicate more time spent in that grid block.

File Name


Set histogram name to file


Same as Histogram_Name=file

The histogram file name is the name of the file in which to write the histogram data. If the file name is not specified it will default to histgram.ext, where ext is based on the file type specified previously. Note that if the histogram name is specified the file name extension should match the file type.

Grid Size

Set histogram grid to nn by mm

Same as

The histogram grid size gives the number of times the image is split up in both the horizontal and vertical directions. For example

 povray +Isample +W640 +H480 +HTN +HS160.120 +HNhistogrm.png

will split the image into 160*120 grid blocks, each of size 4*4 pixels, and output a PNG file, suitable for viewing or for use as a heightfield. Smaller numbers for the grid size mean more pixels are put into the same grid block. With CSV output, the number of values output is the same as the number of grid blocks specified. For the other formats the image size is identical to the rendered image rather than the specified grid size, to allow easy comparison between the histogram and the rendered image. If the histogram grid size is not specified, it will default to the same size as the image, so there will be one grid block per pixel.

Note that on systems that do task-switching or multi-tasking the histogram may not exactly represent the amount of time POV-Ray spent in a given grid block since the histogram is based on real time rather than CPU time. As a result, time may be spent for operating system overhead or on other tasks running at the same time. This will cause the histogram to have speckling, noise or large spikes. This can be reduced by decreasing the grid size so that more pixels are averaged into a given grid block.

Previous:File Output Options   Main Index   Next:Scene Parsing Options