WinCC 7.0 Custom Object Library: Embed Pictures Permanently

When a customized WinCC object that contains a graphic is dragged into the Global Library and then instantiated in a different project, the bitmap is frequently replaced by a red question mark or an empty frame. The behavior is not a defect in the WinCC Graphics Designer; it is the documented consequence of the Picture Referenced property being left at its default value of YES. This article explains the underlying file architecture, walks through the procedure to embed a picture inside the custom object, and provides a complete file-distribution checklist for cases where a referenced picture must remain a referenced picture.

1. Problem Description

A graphics designer creates a compound object on a process picture. The compound object contains, among other things, a single Graphic Object that displays a .bmp file stored in the project's GraCS folder. The compound object is then dragged into a folder in the Global Library palette. The project is closed. A new, empty project is created. The library entry is dragged from the Global Library onto a picture of the new project. The picture opens, the object geometry is correct, and the configured tag connections, animations, and event scripts are preserved, but the picture itself is missing.

Symptoms in the new project:

• Graphic Object displays a red X or a placeholder frame.
• Runtime: a runtime warning Picture "XYZ.bmp" not found is written to Diagnostics of the WinCC Explorer.
• The picture is still present in the original project's <Project>\GraCS\ folder, but it was never copied into the new project's GraCS folder.

The root cause is the Picture Referenced property. When this property is YES (default), the Graphic Object stores only the relative path and filename of the bitmap, for example MyPic.bmp. The actual .bmp remains an external file. The Global Library entry contains a copy of the configuration, not a copy of the bitmap. When the object is placed in a project that does not already contain the referenced file, the lookup fails.

2. Architecture: Global Library File Structure

Understanding the file layout is essential to choosing the correct fix. The Global Library is stored as a single .pxl (Process eXchange Library) file, not as a folder of loose files.

The .pxl container is essentially a renamed ZIP archive. It contains:

• An XML manifest describing folders, version, and content order.
• Embedded .pdl files representing the custom object templates.
• If Picture Referenced is NO, a copy of the bitmap, packed into the .pdl's internal image section.
• If Picture Referenced is YES, only the filename string; the bitmap stays outside the .pxl.

3. Prerequisites

Before modifying the custom object, confirm the following:

1. WinCC installation with full Graphics Designer license, including the Customized Objects function set. The license is part of the standard RC (Runtime + Configuration) package.
2. Edit privileges on the project. Open WinCC Explorer, right-click the project, and confirm Open in Explorer shows a writable path. WinCC disables editing in runtime-only mode.
3. Source picture files in the project's GraCS folder. Use a bitmap with a 24-bit or 32-bit color depth for crisp scaling; WinCC scales .bmp files at runtime when Scale picture is enabled in the Graphic Object properties.
4. Closed Graphic Designer sessions for any picture that contains the custom object. Editing a custom object while a process picture has it open can corrupt the saved template.
5. A project backup. Always duplicate the project folder before modifying custom objects.

4. The Picture Referenced Property

The Picture Referenced property is a Boolean attribute of every Graphic Object. The default value is YES, meaning the Graphic Object stores a string filename and resolves it relative to the runtime GraCS folder of the active project. Setting it to NO inverts this behavior: the picture is read once, encoded as an internal image buffer, and written into the object's PDL. The original file is no longer required at runtime.

5. Step-by-Step Procedure: Embedding the Picture

The procedure below modifies an existing custom object in a project, embeds its picture, and re-saves the object to the Global Library.

5.1 Open the Custom Object in the Graphics Designer

1. In WinCC Explorer, double-click the picture that contains the custom object, or open the Global Library and double-click the custom object entry to edit it directly.
2. If the object was opened from a process picture, right-click the object and choose Customized Object > Open to enter edit mode. The surrounding picture is greyed out.

5.2 Disable Picture Referenced

1. Click the Graphic Object inside the custom object to select it. If the custom object contains more than one Graphic Object, repeat the procedure for each.
2. Open the Object Properties dialog (right-click > Properties, or press Alt+Enter).
3. Navigate to the Properties tab.
4. Locate the Picture group. The two attributes of interest are Picture Name and Picture Referenced.
5. Click the value column for Picture Referenced and change YES to NO.

5.3 Save the Custom Object

1. Close the custom object edit window. Confirm the Save changes to the custom object dialog with Yes.
2. Save the enclosing process picture (Ctrl+S).

5.4 Drag the Updated Object to the Global Library

1. Select the custom object in the process picture.
2. Drag it into the desired folder of the Global Library palette.
3. Provide a version comment if the library supports versioning (V7.2 and later). The library entry is now self-contained; the bitmap is embedded.

5.5 Validate in a New Project

1. Close the current project.
2. Create a new WinCC project, or open any existing project that does not contain the bitmap.
3. Open any process picture in the Graphics Designer.
4. Open the Global Library and drag the custom object onto the picture.
5. Verify the picture renders correctly without copying the bitmap manually.
6. Start runtime and confirm the picture displays the same as in the source project.

6. Trade-offs of Embedding vs Referencing

Choosing Picture Referenced = NO is the right solution when the custom object is genuinely static. For a custom object that needs to support picture swaps without re-saving the library entry, the choice is less clear. The table below summarizes the engineering trade-offs.

7. Hybrid Approach: A Flexible Library With a Distribution Script

For organizations that maintain a library of dozens of custom objects across many projects, the recommended pattern is to keep Picture Referenced = YES and automate the file distribution. The procedure below replicates the file dependencies of a custom object across any project that uses the library.

7.1 Identify the File Set

For each custom object in the library, gather the following files from the source project:

1. All referenced bitmaps from <SourceProject>\GraCS\. Filter by the filenames that appear in the Picture Name attributes of Graphic Objects inside the custom object. Useful command to enumerate referenced picture names from a PDL (after extracting the binary PDL is not necessary; the names are visible in the Graphics Designer):

REM list_dependencies.bat - run from a developer workstation with the source project open
set SRC=C:\WinCC_Projects\BaseProject
set DST=C:\WinCC_Projects\TargetProject

REM 1. Copy referenced bitmaps
xcopy /Y /I "%SRC%\GraCS\*.bmp" "%DST%\GraCS\"
xcopy /Y /I "%SRC%\GraCS\*.emf" "%DST%\GraCS\"
xcopy /Y /I "%SRC%\GraCS\*.png" "%DST%\GraCS\"

REM 2. Copy the library container
copy /Y "%SRC%\library\ProjectLibrary.pxl" "%DST%\library\ProjectLibrary.pxl"

REM 3. Copy global scripts referenced by events on the custom object
xcopy /Y /I "%SRC%\ScriptLib\*.pas" "%DST%\ScriptLib\"
xcopy /Y /I "%SRC%\ScriptLib\*.vb"  "%DST%\ScriptLib\"

REM 4. Copy any additional GraCS resources that the object depends on
REM    (e.g. faceplates, .pdl files called by the object via IncludePicture)

7.2 Distribute via Project Duplicator

The Project Duplicator (WinCC Explorer > Tools > Project Duplicator) copies the entire project including GraCS, library, and ScriptLib. Use it when the new project is a complete copy of the source. Use the manual xcopy procedure above when the new project already exists and only the library and its assets must be merged.

7.3 Versioned Distribution

For WinCC V7.2 and later, the Global Library supports versioned entries. Use the Save As Version function in the Global Library palette context menu to create an immutable version tag. Distribute a known-good version alongside a manifest that lists the .bmp files to be copied. A sample manifest:

# manifest.txt for CustomObject_MotorIndicator v1.4
LibraryEntry=ProjectLibrary.pxl|CustomObjects|MotorIndicator
PictureFiles=
  MotorRun.bmp
  MotorStop.bmp
  MotorFault.bmp
Scripts=
  MotorIndicator_Click.pas
  MotorIndicator_Flash.vb
  

This manifest is the input to a deployment script. When the library version is updated, both the .pxl and the manifest are exported; the target project's deployment script uses the manifest to copy the correct supporting files.

8. Verification Checklist

After performing the embedding or the hybrid distribution, run the following verification checks before handing the project back to the operator.

9. Troubleshooting Matrix

10. Best Practices for a Maintainable Global Library

1. Decide referenced vs embedded per object, not per library. Static pictograms (e.g. logo, separator, frame) are good candidates for embedding. State indicators (run, stop, fault) that change frequently are better referenced with a deployment script.
2. Use a single naming convention for bitmaps. Prefix with the library entry name, e.g. MotorIndicator_Run.bmp. This makes the GraCS folder self-documenting and simplifies the deployment script.
3. Limit the resolution of embedded bitmaps. An 800 x 600 24-bit .bmp is 1.4 MB; an 80 x 60 24-bit .bmp is 14 KB. Most operator screens display 16 x 16 to 64 x 64 icons. Use the resolution that matches the display size.
4. Keep one .pxl per logical group. A ProjectLibrary.pxl with hundreds of entries is hard to version. Split by domain (motors, valves, alarms) and version each independently.
5. Document each custom object. Use the Comment field in the Global Library entry to record the object name, the version, the author, and the list of dependent files. A glance at the palette is then sufficient for the next maintainer.
6. Test in a clean project. Before promoting a library version to production, instantiate every entry in a fresh project and verify visually. The cost of the test is minutes; the cost of a missing picture in a 24/7 plant is significant.
7. Lock the library version per project. Once a project is commissioned, freeze the library version. Future projects start from a new branch of the library.
8. Back up the library folder separately. The library folder is small but high-value. A nightly copy of *.pxl files is inexpensive insurance.

11. Edge Cases and Field Notes

11.1 Custom Objects Inside Custom Objects

If a custom object contains another custom object (nested compound objects), the Picture Referenced property must be reviewed for every Graphic Object at every level. The embedding operation is not transitive: setting the property on the outer custom object does not change the inner custom object's references.

11.2 VBScript Event Handlers Referencing Picture Files

A common pattern is to call HMIRuntime.BaseScreenName = "MyScreen.pdl" from a click event on a custom object. The custom object itself may have an embedded picture, but the script still references a separate process picture. The deployment script must include the referenced PDL in the file list. Embedding does not help here.

11.3 Migration from WinCC V6 to V7

Custom objects created in V6 used the older .pdl format. When dragged into a V7 project and re-saved, the Graphics Designer upgrades the format. If a V6 custom object was embedded and then migrated, the picture block survives but may render at a different size due to V7's default DPI handling. Verify the picture size in the migrated project.

11.4 Multi-User Engineering with WinCC Team Engineering

If the project uses the optional Team Engineering add-on, multiple engineers may edit the same custom object concurrently. The last save wins for the embedded picture. Use the source-control integration of Team Engineering to merge changes deliberately; never rely on the file system to resolve conflicts.

11.5 OPC UA / Symbolic Linking

If the custom object uses tag connections, the connection strings are stored inside the embedded PDL. After embedding, the tag names are locked to those that were configured in the source project. If the target project uses a different tag namespace, the connections will be invalid even though the picture renders. Verify tag connections as part of the verification checklist.

12. Diagnostic Procedures for Missing Pictures

When a custom object is reported as missing its picture, the following diagnostic steps isolate the cause.

1. Read the Picture Referenced property. In the Graphics Designer, open the custom object and inspect the Graphic Object. If the value is YES, the file must exist in the target project's GraCS folder.
2. Compare file checksums. Use fc /b on Windows to compare the .bmp in the source and target GraCS folders. A mismatch indicates a stale file.
3. Check the WinCC runtime log. In WinCC Explorer, expand Diagnostics and review the *.log file. Search for the bitmap filename. The exact log entry is typically:
   Picture "<filename>.bmp" not found.
4. Check path resolution. WinCC resolves filenames relative to the runtime GraCS folder. An absolute path such as C:\WinCC_Projects\BaseProject\GraCS\MyPic.bmp will fail in any project whose path differs. Always use bare filenames.
5. Check the file extension case. WinCC is case-insensitive on most Windows file systems, but the .pxl archive stores the case as configured. Mismatched case may produce a missing picture on a case-sensitive file system, although this is rare in practice.
6. Check the Scale picture and Picture transparent options. A picture that appears missing may simply be rendered fully transparent due to a misconfigured color key.

13. Reference: Property Mappings

The following parameter mapping summarizes the configuration surface of a Graphic Object in the context of library transfer.

14. Reference: Common File Locations

15. Summary

The default behavior of the Global Library is to store custom objects with Picture Referenced = YES. This is the most flexible choice for a single project, but it forces the engineer to copy the supporting bitmap files into every new project. For a self-contained custom object, set Picture Referenced = NO in the Graphic Object's properties and re-save the object to the library. The trade-off is loss of easy picture updates and a larger library entry.

For organizations with many custom objects and many projects, the recommended pattern is to keep references active and to automate the file distribution. The cost is a deployment script; the benefit is small, version-controlled library entries with fast picture updates.

Either approach, when applied consistently and verified against the checklist in Section 8, produces a maintainable Global Library that survives project migration, project duplication, and team handovers.