# Pattern Data

The Pattern Data View is a simple tree representation of the Patterns generated by the Pattern Language source code that has been executed in the Pattern Editor View. These two views work hand in hand. By default, the table in this view will be completely empty until any Pattern Language source code is executed and that code places any type into the loaded data throught the placement syntax. ### Structure of the patterns The table in the Pattern Data view consists of six columns: * `Name`: This column simply displays the name of this pattern. The name is either the name of the variable or a customized string set through the `[[name("value")]]` attribute. * `Color`: This column shows the color of this pattern as it's highlighted in the Hex Editor View. This color is usually selected from a repeating color pallette but can also be manually assigned using the `[[color("RRGGBB")]]` attribute. * `Offset`: This colum shows the start and end address of the pattern where it has been placed into the data. * `Size`: This column shows the size of the pattern. * `Type`: This column displays a formatted version of this pattern's Type name. * `Value`: This column is the most important one as it displays the value that this pattern has decoded from the data it was placed on. ### Interacting with the patterns Each line in the table corresponds to one pattern that was generated. Simple patterns such as a `u32` will stand on their own and simply display their decoded value. Other more complicated patterns such as custom struct types might have children that can be displayed. If a pattern has any children, an arrow icon appears to the left of their name. Clicking on the name will expand the tree view of that pattern and display its children. Clicking anywhere else on the pattern will cause the Hex Editor View to jump to the address of this pattern and select it. When bytes are being selected in the Hex Editor View, some of the names of the patterns might turn blue. This color indicates that the current selection in the Hex Editor View overlaps with this pattern or one of its children. ### Modifying pattern values Most built-in pattern types as well as custom types that have been attributed with the `[[format_write]]` attribute can be modifed by double clicking their `Value` field. Doing so will turn the `Value` field into a text box where the new value can be entered. Pressing the `Enter` key will cause the pattern to format the entered value and write the bytes back into the data where the pattern has been placed at. ### Visualizers Visualizers are a ImHex-specific extension to the Pattern Language. They allow you to visualize data in more advanced ways than by just using text and colors. To use a visualizer, simply apply the `[[hex::visualize("visualizer_name", params...)]]` attribute to the type or variable you want to visualize. ```cpp struct Coordinates { float latitude; float longitude; } [[hex::visualize("coordinates", latitude, longitude)]]; ``` The entry in the Value column will then turn into a Button

that will open the visualizer popup with the specific visualization inside. #### Available Visualizers `[[hex::visualize("line_plot", float_array)]]` This visualizer expects an array of 4 Byte `float` values and will visualize it using a Line Plot

`[[hex::visualize("scatter_plot", x_float_array, y_float_array)]]` This visualizer expects two arrays of 4 Byte `float` values and will visualize it as a Scatter Plot using the first array for the X Coordinates and the second array for the Y Coordinates. These two arrays need to have the same size.

`[[hex::visualize("image", pattern)]]` This visualizer expects any pattern that contains the bytes of an image (such as a struct, a byte array and so on) and will decode the data into the actual image data. Supported formats are: JPG, PNG, TGA, BMP, PSD, GIF, HDR and PIC

`[[hex::visualize("bitmap", pattern, width, height)]]` This visualizer expects any pattern that contains raw RGBA8 values in the form of `RR GG BB AA`, one byte per color channel as well as the width and height in pixels of the resulting image. It will draw these bytes as is.

`[[hex::visualize("bitmap", pattern, width, height, clutData)]]` Image visualizer can also display [indexed images](https://en.wikipedia.org/wiki/Indexed_color). The fifth argument for this visualiser is the color lookup table (CLUT). The CLUT always has to be in 32-bit RGBA color format. If your lookup table uses diferent color format, use the [transform attribute](https://github.com/WerWolv/Documentation/blob/master/pattern_language/core-language/attributes.md#transform_entriestransformer_function_name) to remap your color to 32-bit RGBA. See the examples below. ```rust import type.color; #define WIDTH 128 #define HEIGHT 128 struct Data { u8 imageData[WIDTH * HEIGHT]; type::RGBA8 clutData[256]; } [[hex::visualize("bitmap", imageData, WIDTH, HEIGHT, clutData)]]; Data data @ 0; ``` The following example illustrates how to transform the CLUT table from `RGBA5551` format to `RGBA8` using the transform attribute. ```rust #define WIDTH 128 #define HEIGHT 128 bitfield RGBA5551 { r : 5; g : 5; b : 5; a : 1; } [[sealed, transform("to_u32"), format("as_u32")]]; fn uq(auto v) { // unquantize return u32(float(v) * 255f / 31f); }; fn to_u32(auto v) { return uq(v.r) + (uq(v.g) << 8) + (uq(v.b) << 16) + 0xFF000000; }; fn as_u32(auto v) { return std::format("{:#x}", v); }; struct Image{ u8 imageData[WIDTH * HEIGHT]; RGBA5551 colors[256]; }[[hex::visualize("bitmap", imageData, WIDTH, HEIGHT, colors)]]; ``` The visualizer supports indices of 4 (16 colors), 8 (256 colors) and 16 (65536 colors) bits. The indices array can be provided as an array of any integral type. The only requirement is that the array is of the correct amount of bytes. ```rust import type.color; #define WIDTH 16 #define HEIGHT 32 struct Data { // In this example we read 4-bit indices in an array of u8. // The length of the u8 array is actually half the size of // the underlying number of nibbles representing indices. u8 imageData[16 * 16]; type::RGBA8 clutData[16]; } [[hex::visualize("bitmap", imageData, WIDTH, HEIGHT, clutData)]] ``` `[[hex::visualize("sound", pattern, num_channels, sample_rate)]]` This visualizer expects any pattern that contains all the bytes of a raw signed 16-bit PCM audio stream, the number of channels that are being used and the sample rate. It allows you to convert this data to sound to listen to.

`[[hex::visualize("3d", vertices, indices)]]` This visualizer expects an array of structures containing three 4-Byte `float` values, representing X, Y and Z coordinates of each vertex in a model and an optional `u32` array containing indices into the vertices array. `null` can be used for the indicies array if it shouldn't be used.

Each group of 3 vertices makes a triangle and there are two ways to represent these triangles: * If indices array is `null`, then vertices array should contain N\*3 vertices, to represent N triangles of a model. * Otherwise, the indices array should contain N\*3 indices, each group representing a triangle by indexing into the vertices array. For example: * Vertices array containing 12 elements will represent 4 triangles, array elements with indices 0,1,2 representing the first triangle, indices 3,4,5 representing the second triangle and so on. * Vertices array containing 5 elements can also represent 4 triangles by using a 12-element `indices` array - every group of 3 elements in that array representing a triangle, so indices array elements with indices 0,1,2 is the first triangle, indices 3,4,5 are the second triangle and so on.

With the above example of four triangles these two representations are equivalent: * with `vertices` array only ``` vertices = [ // 1st triangle { -1.0, -1.0, 0.0 }, // vertex (0) { 1.0, -1.0, 0.0 }, // vertex (1) { 0.0, 0.0, 0.0 }, // vertex (2) // 2nd triangle { 1.0, -1.0, 0.0 }, // vertex (1) { 0.0, 0.0, 0.0 }, // vertex (2) { 1.0, 1.0, 0.0 }, // vertex (3) // 3rd triangle { 1.0, 1.0, 0.0 }, // vertex (3) { 0.0, 0.0, 0.0 }, // vertex (2) { -1.0, 1.0, 0.0 }, // vertex (4) // 4th triangle { -1.0, 1.0, 0.0 }, // vertex (4) { 0.0, 0.0, 0.0 }, // vertex (2) { -1.0, -1.0, 0.0 }, // vertex (0) ] ``` * or, with both `vertices` and `indices` arrays ``` vertices = [ { -1.0, -1.0, 0.0 }, // vertex (0) { 1.0, -1.0, 0.0 }, // vertex (1) { 0.0, 0.0, 0.0 }, // vertex (2) { 1.0, 1.0, 0.0 }, // vertex (3) { -1.0, 1.0, 0.0 }, // vertex (4) ] indices = [ // 1st triangle 0, 1, 2, // 2nd triangle 1, 2, 3, // 3rd triangle 2, 3, 4, // 4th triangle 4, 2, 0 ] ``` `[[hex::visualize("chunk_entropy", pattern, chunk_size)]]` This visualizer expects any pattern whose bytes will be split into chunks of the size specified by the `chunk_size` parameter. It will then display an entropy graph of these bytes

`[[hex::visualize("hex_viewer", pattern)]]` This visualizer expects any pattern whose bytes will be displayed in a hex viewer similar to the one in the hex editor view. This is mainly useful for splitting out large chunks of bytes and looking at them individually or for debugging when getting patterns into the right format for other visualizers to work with.

`[[hex::visualize("coordinates", latitude, longitude)]]` This visualizer expects a latitude and longitude value in form of a floating point number and visualizes this coordinate on a map of our planet. It also allows for checking the internet for the approximate name / address of this location.

### Inline Visualizers Inline visualizers work the same as the normal visualizers but instead of displaying in a separate popup window, they replace the value drawn in the Value column. `[[hex::inline_visualize("color", r, g, b, a)]]` This visualizer expects separate r, g, b and a color values, each ranging from 0 to 255. It displays this color then in the value column.

`[[hex::inline_visualize("gauge", progress)]]` This visualizer expects a progress value ranging from 0 to 100. It displays this value as a progress bar where 0 means the progress bar is entirely empty and 100 means it's completely filled.

`[[hex::inline_visualize("button", function_name)]]` This visualizer replaces the value column with a button that executes the specified function when clicked. It expects the name of the function as a string.

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.werwolv.net/imhex/views/pattern-data.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.