Files
Introduction
This tutorial demonstrates how to work with a raster that appears black when viewed in Data Preview despite having varying pixel values.
The Record Information window shows that the image consists of three 16-bit bands, which defines an RGB48 interpretation. This means that the range of available values for each band goes from 0 to 65535. However, the actual values on the sample image do not exceed a few hundred.
In other words, this raster contains 8-bit values stored in 16-bit bands.
The completely black display is partly due to how FME interprets the data; 0 is black and 65535 is white, so even a value of 255 will appear dark. But this is also a problem with the data. Either the correct interpretation needs to be set on the existing values, or the values need adjusting to match the current interpretation.
One way to solve this issue is to use the RasterInterpretationCoercer. In this example, we want to convert the RGB48 raster to RGB24. In this transformer, we would set the Destination Interpretation Type to RGB24 and then choose a conversion option. There are four conversion options, giving users control over the process. This tutorial covers each conversion option and shows the output to demonstrate its effects.
The conversion options include:
- Cast: Direct conversion with no rescaling; outer values are wrapped
- Bounded Cast: Direct conversion, but clamps outside values to the destination min/max
- Scale by data values: Rescales values using actual source min/max values, while preserving proportions
- Scale by data type: Rescales values using full source and destination ranges
The images below show the output with varying conversion settings set in a RasterInterpretationCoercer:
Cast
The Cast conversion is a direct conversion with no rescaling, so the values of each pixel are the same in the new RGB24 interpretation as they were with RGB48. The orthophoto can now be seen properly because the range for 8-bit imagery is 0–255, and the color values are therefore interpreted correctly.
Bounded Cast
The Bounded Cast conversion is also a direct conversion, but any values that are above or below the maximum and minimum bounds for the destination interpretation type will be clamped to the max/min. Any pixel values below 0 will be set to 0, and any pixel values above 255 will be set to 255. In this example, the Bounded Cast conversion produces the same output as the Cast conversion because all values were between 0 and 255 in the original image.
Scale by Data Values
The Scale by Data Values conversion takes the actual minimum and maximum of the source image and rescales the values using the destination interpretation type min/max. The output image looks different from the Cast and Bounded Cast conversions due to the differing max/min values of the source image. In this example, the green and blue bands have a range of 0 to 255, but the maximum red band value is 242 (these values can be extracted using a RasterBandMinMaxExtractor). This means that during rescaling, the red band will be stretched more than the blue and green bands, leading to a boost in red values and an overall more red-looking image.
Scale by Data Type
The Scale by Data Type conversion takes the full theoretical range of the source image and rescales it to the destination range. In this example, scaling by data type is not a good choice because the full theoretical range of the source image is 0–65535 whereas the actual range only reaches a maximum of 255. The calculation would be:
pixel value / max source theoretical value * destination max value256 / 65535 * 256 = 1In this case, this results in every pixel rounding to either 0 or 1. Scaling by data type can be useful in scenarios where the original raster image already has values stored at the correct bit depth and the goal is simply to downscale the raster to a lower bit depth.
For more details on how the conversion options work, see the RasterInterpretationCoercer documentation.
Step-by-Step Instructions
In Part 1, a checkered black and white raster is used to visualize the differences between conversion types using the same method described above, and pixel values are compared.
In Part 2, an RGBA raster is used — where alpha values set the transparency to increase farther from the area of interest — and it is converted to an RGB raster using two methods to handle the alpha band removal.
The source data and template workspaces used in this tutorial can be downloaded from the Files section.
Part 1: Conversion Types
To better visualize the raster conversion types, multiple RasterInterpretationCoercers are applied to a checkered raster, and the output pixel values are compared to the source image.
1. Open FME Workbench
Open FME Workbench and start a new workspace.
2. Add a RasterNumericCreator
On the top menu, click Add Transformer. In the Add Transformer dialog, search for RasterNumericCreator and click OK to add it to the canvas.
Double-click the transformer to open the parameters and set the following:
- Resolution Specification: Rows and Columns
- Number of Columns (cells): 25
- Number of Rows (cells): 25
- X Cell Spacing: 1
- Y Cell Spacing: 1
- Interpretation: UInt16
- Min. Numeric Value: 0
- Max. Numeric Value: 5000
- Data Pattern: Checkered Pattern
These parameters create a 25x25 cell raster of type UInt16 (theoretical values range from 0 to 65535) with actual values ranging from 0 to 5000, displayed in a checkered pattern.
Enable Feature Caching and run the workspace. Once the run is complete, click the green eye icon on the RasterNumericCreator to open the data cache in Data Preview. The raster will look like this:
This display has been stretched for better display in FME using the actual range of values. To see the true image, write the raster to GeoTIFF. This raster would appear black if exported to GeoTIFF and viewed, since the values do not cover the full theoretical range. FME renders the image using grayscale, with the minimum value (0) set to black and the maximum value (5000) set to white for display. When viewing the GeoTIFF in FME Data Inspector or Data Preview, it will look like this:
This is a 16-bit data type (UInt16). To make the file size smaller, it will be converted to UInt8, which is 8-bit. The pixel values will need to be scaled down to match the large range.
3. Add RasterInterpretationCoercers
We will convert the raster to UInt8 using the four conversion methods. Add four RasterInterpretationCoercers and connect each Input port to the RasterNumericCreator Created port:
Double-click each RasterInterpretationCoercer to open the parameters and set the destination interpretation type for all four transformers:
- Destination Type: UInt8
Now set the conversion types in each transformer to a different type. Since the raster created here is a numeric raster, only the Convert from Numeric to Numeric setting strictly needs to change, but it is good practice to set both:
-
Convert from Color to Numeric: [conversion type]
- Cast, Bounded Cast, Scale by Data Values, or Scale by Data Type
-
Convert from Numeric to Numeric: [conversion type]
- Cast, Bounded Cast, Scale by Data Values, or Scale by Data Type
4. Write to GeoTIFF
We will write the outputs to GeoTIFF files for viewing.
In the Toolbar, click the Add Writer button. In the Add Writer dialog, set the following:
- Format: GeoTIFF (Geo-referenced Tagged Image File Format)
-
Dataset: /Output
- Browse to an output folder
Click OK. In the Feature Type dialog, set the file name:
- Raster File Name: CheckeredCast
Click OK to add the writer to the canvas. Select the CheckeredCast GeoTIFF writer feature type on the canvas, right-click the writer feature type, then click Duplicate.
Repeat this process three more times, for a total of five GeoTIFF writer feature types.
Double-click into each writer feature type to edit the file name in the Feature Type parameters. The five file names are:
- CheckeredCast
- CheckeredBoundedCast
- CheckeredDataValues
- CheckeredDataType
- OriginalRaster
Connect each writer feature type to its associated RasterInterpretationCoercer conversion type Output port:
5. Run Workspace and View Output
Click the green Run button in the Toolbar to run the workspace. Once the translation succeeds, select each writer feature type and click the View Written Data button in the Mini Toolbar to view the output.
We will inspect the values of the original and output rasters to understand the conversion process.
Cast
The Cast conversion is a direct conversion with no rescaling. Values in the new UInt8 interpretation are the same as they were in UInt16, as long as they are within the UInt8 range (0–255). Values outside that range are wrapped using the modulo value. For example, the value of 5000 in the original image has been converted to 136. The steps below show how this remainder value is calculated.
Calculation:
- Divide the original pixel value by the number of possible values in the destination:
5000 / 256 = 19.531 - Truncate the result (drop the decimals):
19 - Multiply the result by the number of possible values in the destination:
19 * 256 = 4864 - Subtract the result from the original pixel value to calculate the remainder (modulo):
5000 - 4864 = 136
Before conversion:
After converting using the Cast method:
When processing this raster, avoid using the Cast conversion option, as it compromises the visual integrity of the image. The output does not match the original because any cell values outside the 0–255 range are not scaled — instead, they are calculated based on their remainder, causing the pixels to wrap around and distort the image.
Bounded Cast
The Bounded Cast conversion is also a direct conversion, but any values above or below the maximum and minimum bounds for the destination interpretation type are clamped to the max/min rather than wrapped. For this raster, any values above 255 are clamped to 255, and any values below 0 are clamped to 0. The checkered pattern alternates between a higher value and 0, so the 0 pixels remain 0 and the values above 255 are set to 255. Since the maximum value was set to 5000 in the RasterNumericCreator, most pixel values exceed 255, and much of the output image therefore contains pixels with a value of either 0 or 255. The top rows contain pixel values lower than 255 and remain unchanged. The image below shows a pixel in the original raster that had a value of 2371 and was set to 255 in the new image.
Before conversion:
After converting using the Bounded Cast method:
When processing this raster, avoid using the Bounded Cast conversion option, as it converts most pixel values to 255. The output does not match the original because any cell values outside the 0–255 range are clamped to either 0 or 255.
Scale by Data Values
The Scale by Data Values conversion takes the source raster's actual min and max values and rescales them using the destination min/max.
The raster minimum and maximum values can be found using a RasterBandMinMaxExtractor and inspecting the Record Information window in its output.
In the RasterNumericCreator, the minimum value was set to 0 and the maximum to 5000. Scaling by data values treats this as the full range, then rescales to fit within the destination interpretation range. Scaling to UInt8 means converting to fit in the range 0–255. The calculation is: pixel value / max original value * destination max value.
Before conversion:
After converting using the Scale by Data Values method:
If the pixel values are intentionally low and do not use the entire theoretical range for a specific reason, scaling by data values may not be the best choice. However, if the original raster has lower values and cannot be properly visualized, scaling by data values stretches the range of original pixel values to the full theoretical range of the destination interpretation type.
Scale by Data Type
The Scale by Data Type conversion scales the data using the entire possible range of the source image (rather than the actual range, as Scale by Data Values does) and fits it to the destination range. In this case, the theoretical maximum value is 65535, but the actual maximum value is 5000, meaning the conversion results in mostly low values — which produces a raster that looks visually identical to the original GeoTIFF output.
The calculation is: pixel value / max source theoretical value * destination max value. In this case, this results in every pixel rounding to either 0 or 1 (256 / 65535 * 256 = 1). Scaling by data type can be useful in scenarios where the original raster image already has values stored at the correct bit depth and the goal is simply to downscale the raster to a lower bit depth.
Before conversion:
After converting using the Scale by Data Type method:
To summarize: The first two options, Cast and Bounded Cast, are better for keeping the original values, under the condition that the destination range is large enough to fit all the values. The last two options, Scale by Data Values and Scale by Data Type, help preserve the visual representation.
Part 2: RGBA to RGB
The RGBA to RGB option in the RasterInterpretationCoercer tells the transformer what to do when converting an RGBA image (an image with three color bands plus an alpha band responsible for transparency) into an RGB image (color only).
In this example, the source RGBA32 raster has an area where transparency fades gradually toward full transparency using the alpha band as the viewer moves farther from the area of interest. This is converted to an RGB24 raster using two different methods — one by removing the alpha band and exposing the full image, and one by applying the alpha band and adjusting the RGB values to reflect it.
1. Read Raster Data
Open FME Workbench and start a new workspace. In the Toolbar, click Add Reader. In the Add Reader dialog, set the following:
- Format: PNG (Portable Network Graphics)
-
Dataset: /RGBA-Raster.png
- Click the ellipsis button and browse to the downloaded source dataset
Click OK. Enable Feature Caching and run the workspace. Once the translation succeeds, click the green eye icon on the reader feature type to open the data cache in Visual Preview.
The pixel values can be viewed by selecting a point on the raster and noting the band values in the Record Information pane.
The first three bands (Red, Green, Blue) reflect the actual pixel values, while the Alpha band reflects the degree of transparency. The image below shows a point in the raster that has transparency set to 50, so it is semi-transparent:
2. Drop the Alpha Band
Add a RasterInterpretationCoercer transformer and connect its Input port to the PNGRASTER reader feature type.
Double-click the transformer to open the parameters and set the following:
- Destination Interpretation Type: RGB24
- RGBA to RGB: Drop the alpha band
Selecting Drop the alpha band removes the alpha band and reveals what was hidden by the transparency of the alpha pixels. Note that the RGB band values have changed and now reflect the original values without alpha influence.
3. Apply the Alpha Band
Add another RasterInterpretationCoercer to the canvas and connect its Input port to the PNGRASTER reader feature type:
Double-click the second RasterInterpretationCoercer (RasterInterpretationCoercer_2) to open the parameters and set the following:
- Destination Interpretation Type: RGB24
- RGBA to RGB: Apply the alpha band
Selecting Apply the alpha band still produces the gradual fade of the image contents, but the interpretation is now RGB24 and the remaining band values (RGB) have changed to reflect the application of the alpha band.
4. Write to PNG
The two outputs will be written to PNG and viewed in Data Preview. In the Toolbar, click Add Writer. In the Add Writer dialog, set the following:
- Format: PNG (Portable Network Graphics)
-
Dataset: /Output
- Set an output directory
Click OK. In the Feature Type dialog, set the Raster File Name:
- Raster File Name: AlphaRemoved
Click OK to add the writer, then connect it to the first RasterInterpretationCoercer Output port.
Right-click the AlphaRemoved writer feature type and click Duplicate from the menu. Double-click the duplicated writer feature type to open the parameters and set the Raster File Name:
- Raster File Name: AlphaApplied
Click OK and connect it to the second RasterInterpretationCoercer Output port.
5. Run Workspace and View Output
Click the green Run button in the Toolbar to run the full workspace. Once the translation succeeds, select the AlphaRemoved writer feature type and click the View Written Data button:
The raster will open in Data Preview. The output shows the entire image revealed with no transparency set.
Now view the AlphaApplied data. The raster appears to have transparency set, but when the Record Information window is checked, there is no alpha band. The alpha values have been applied to the RGB bands to reflect the transparency.
Additional Resources
RasterInterpretationCoercer [FME Documentation]
Alpha Compositing: Blending Two Raster Images [Article]
Alpha Compositing: Transitioning to White [Article]
Data Attribution
The data used here originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.