About Mapper3d

The Mapper3d program is used for managing all aspects of a 3d calibration and for exporting the results to the corresponding warp units.

Based on any available calibration the following options are available:

access to many parameters of the projection setup, like IP addresses, image resolution and projector resolution
displaying test data on the screens using the PatternGenerator program installed on the image generator machines
managing view port settings like viewer position or projection area
changing and applying all aspects of blending and image operations
exporting the result data for different warp units/software or image generators

Main window overview

Mapper3d has a fully configurable workspace. Figure above shows the default configuration with the typical widgets open.

Menus

File Menu

Load and save projects. Adjust global project settings.

Export Menu

Export calibration data from current project using available exporters. Please refer to section Exporters for a list of all available exporters.

Export settings used here are non-persistent. This is useful for experimenting with different settings, without changing a previously defined autoalignment work-flow for instance. Section Pipeline Editor describes how to save persistent export settings using the Pipeline Editor.

Extras Menu

Additional tools and advanced operations on loaded project.

View Menu

Workspace and theme management.

Help Menu

Help, Support and Program information.

Toolbar

The toolbar provides quick access to several previews (see Preview Toolbar) and an automization run.

Docks

Here a list of the most important docks, also shown in the screen shot.

Projector List: The projectors dock widget shows a list of all projectors in the current project and allows to edit projector related settings.
Mapping: 2D mapping of the projection, used for applying clipping, fadeout and calculating blending.
Pipeline Editor: On the right side in the Pipeline Editor exporters can be configured with persistent settings to run multiple times.

Central Views

In the center of the window are multiple views available between which the user can switch.

Mapping 3D: Shows the warping between virtual camera and selected projection channel.
Mapping 2D: Shows the 2d warping between screen mapping and selected projection channels.
3D: Shows projection surface, mapping and virtual cameras in a 3d view.

All dock widgets can be arranged, stacked, opened and closed by user. The workspace layout is saved persistently.

It is also possible to revert to the default workspace using View/Default Workspace.

All available dock widgets can be found in the menu. They are described in the following sections.

The theme can be switched in View/Theme. An application restart is needed for a theme switch to take effect.

For using the maximum workspace on the desktop, a full screen mode can be enabled in View/Toggle Fullscreen Mode.

Projector List

There are different kinds of information stored for each projector. All values are managed by the tabs below the projector list, which apply to the selected projectors.

The list shows the given Projector name, its IP address with port, the resolution and if an alignment is available (aligned).

The projector list is multi-selection enabled. Only selected projectors are shown in the 2d- and 3d-view. Press Ctrl-A to select all projectors at once or hold Ctrl- or Shift-key to add projectors to current selection.

By selecting any projector inside, all fields in the settings tabs are updated and all previous modifications to it are applied.

Viewpoint

The viewpoint pull down menu is used to manage different sets of projector view settings. Its main use is to switch safely and quickly between different eye-points, like pilot’s positions in a simulator. Switching between viewpoint groups does not modify the resulting projection immediately, you have to export the project again (most commonly through running the exporter pipeline again).

Selection: If multiple viewpoints are defined in the project, select the current viewpoint for editing.
Add Viewpoint: Add a new mapping to the project.
Duplicate Viewpoint: Duplicate the currently selected viewpoint.
Remove Viewpoint: Remove the currently selected viewpoint. This is only possible when more than one viewpoint is present in the project.

See Viewpoint for details about viewpoints and how to setup.

General settings

First there are the general settings, which reflect the physical setup. Usually all data here is filled out in advance through the calibration process and its setup.

Name

Human readable string describing the projector.

Type

Interface to use for showing testpatterns.

OSC Single: Default PatternGenerator based interface. Works with up to date PatternGenerator.
OSC Multi: ProjectionTools channels are virtually split into multiple PatternGenerator channels. Works with standard PatternGenerator.
OSC Legacy: Can be used for very old PatternGenerator installations, or installations on limited/embedded hardware. The preview functionality is limited.
NDI: Provide testpatterns as one NDI-stream per channel. This can be used, if it is not possible to install PatternGenerator on the Mediaservers. Several Mediaservers support recieving and showing NDI-Streams. The preview functionality is limited.
Norxe Unify: Send testpatterns as image directly to Norxe Unify projectors. This allows calibration without access to IGs.The preview functionality is limited, and not interactive.
Barco Pulse: Send testpatterns as image directly to Barco Pulse projectors. This allows calibration without access to IGs.The preview functionality is limited, and not interactive.
Luna: Send testpatterns as image directly to domeprojection Luna warp units. This allows calibration without access to IGs.The preview functionality is limited, and not interactive.
Warper4k: Send testpatterns as image directly to Westar Warper4k warp units. This allows calibration without access to IGs.The preview functionality is limited, and not interactive.

IP

Network address of the computer where the PatternGenerator software is running on. Hostnames are supported as well.

Port

Networkport to communicate with PatternGenerator. By default 11000.

Channel

The Channel is used to address a projector - if more than one is connected to a single PC.

Width and height

Have to be the same as the physical projector resolution used in the projection and displayed here for reference only (not editable).

dim X and dim Y

Attribute, defining the resolution of the warping grid. Larger values may gain better results but some constraints apply. There are hard limits depending on the warping unit. Bigger values are increasing the calculation time of many operations significantly, especially blend map calculation.

View settings

The view settings define the output warping depending on a calibration. All properties of the virtual projection camera are managed here. All changes are displayed in the graphical views (Warping, 3D).

Note

The changes are displayed only after pressing the Enter key or change of the input focus, since all modifications to view settings lead to a time consuming recalculation.

The transform group defines the relative position (eye-point) and orientation of the virtual camera per channel.

Position (x,y,z)

The position relative to the center of the systems point of origin. Values entered in millimeter.

Rotation (heading, pitch, bank):

Each virtual camera can be rotated around the defined eyepoint. Note that no setting for all cameras is available, they are usually rotated in different directions. The rotation order is:

heading
pitch
bank

The viewing frustum is setup in the frustum group. There are three different methods for entering/viewing the data. They can be selected with the pull down menu (currently displaying Field of View) and change the input dialogue.

Input Method

Select method for viewing/entering frustum data. Changes input fields below accordingly. Options are:

Field of View: enter the value in degree for the horizontal (HFOV) and vertical (VFOV) field of view. Shift the projection by fractions of 100 with h shift and v shift.
Zoom: enter aspect ratio, zoom, h shift and v shift as fractions of 100.
Separate Angles: enter the four (top, bottom, left, right) opening angles in degree relative to the middle point.

Depth (near, far, target)

Adjust the depths range and target distance. The target depth is used for generating target rectangles for advanced 3d export (see section Export Generic Advanced 3D).

Guess

The Guess button can be used to calculate the frustum and viewpoint orientation, based on the measured data. It will open a dialog with further options. For details see section Viewpoint.

Rotate left/right

Rotate (spins) the frustum in corresponding direction while keeping current frustum shape (switching between portrait and landscape).

Shading settings

The Shading panel expose blending properties which can be different for each projector. There are other values as well, which apply to the whole setup and are adjusted in different places.

Blend Group

In order to increase light intensity, sometimes two projectors are used to project on the same area of the screen. This is a so called “tandem” or “stacked” projection. Since blending is typically calculated between all overlapping projectors, the brightness of the tandem projection pair would be reduced to the brightness of one projector canceling out the initial intention of the tandem projection. The proper use of Blend Groups helps in this case.

Blending is calculated between projectors of same blend group only. Use different blend groups for different layers of projection or projectors between which no blending should be calculated. The blend group element assigns a projector to a blend group. The default blend group is 0.

Brightness

Brightness of projector in lumen. Used for uniformity correction calculations.

Brightness Calculate

Allows to calculate projector brightness from measured brightness of projected image center and a given screen-gain. Shows a small white rectangle on the selected projector center for taking a measurement right away.

Contrast

Contrast of projector, used for advanced black level correction calculations.

Contrast Calcutate

Allows to calculate projector contrast from black and white measured at center of projected image. Shows a black image and a small white image in projector center for taking measurements.

Override Chip Oversize

Allows to override the global chip oversize values. This might be used, when there are different projector types in a projection system. Chip oversize is important for Black Level Correction calculations, see section Black Level Correction for more information about Black Level Correction.

Topology

Touching Channels: Define the neighboring channels for high resolution projectors (See section Touching Channels).
Mapping: Select the mapping used for that channel.

Adjust

Allows to do additional, manual adjustment of geometry and color uniformity.

Shading

Adjust brightness and color up to pixel level.

Brightness Adjust

When global automatic uniformity correction is disabled, it allows to edit custom uniformity correction for a projector. See section Uniformity Correction Editor for details.

Clipping

Allows to clip parts of the current projector. The clipped parts will be covered by neighboring projectors if present. It is usually used, if projectors are partly shadowed by obstacles.

WhitePoint

Allows to adjust the color uniformity of a projector. This correction is combined with the standard uniformity correction of a projector.

Please be aware, that color uniformity correction is not compatible with all systems.

Init Preview:: Uploads blending information to the PatternGenerator, so that an interactive preview can be shown while editing the whitepoint color uniformity.
Reset Preview:: Puts PatternGenerator in a clean state again, compatible with standard previews.
Edit:: Opens an Uniformity Correction Editor (see section Uniformity Correction Editor), with color editing enabled.

Blanking

If a projector has poor projection quality at the edges or corners, these areas can be removed using the blanking option. Adjust the amount of blanking for left, right, top, bottom edge and preview the results using the “Preview Cutting”. This feature does not change the resulting warping. The blanking is encoded in the exported blending as black areas.

Black Level Correction

Control appearance of projection when dark/black content ins projected.

Uniformity

Allows to change the color of the software black level correction. This is sometimes necessary, if the native black of a projector has a different color than the lower gray levels. It is suggested to turn “Advanced BLC” off in project settings and set a relative high “Black Level”, in order to have a good starting point.

It is also possible to adjust multiple projectors at once by selecting the relevant projectors in the projector list and using Extras/BLC Tweak Initialize... followed by Extras/Tweak Black Level Correction....

Note

Please be aware, that colored black level correction is not compatible with all systems.

Init Preview: Prepares the PatternGenerator to show an interactive preview while editing the black level color uniformity.
Reset Preview: Puts PatternGenerator in a clean state again, compatible with standard previews.
Edit: Opens an Uniformity Correction Editor (see section Uniformity Correction Editor), with color editing enabled.

Override Chip Oversize

Overrides the globally set Chip Oversize per projector (see section Shading).

Geometry

Allows to slightly adjust the warping. It is rarely used to handle errors or unusual setups, which are not covered by standard attributes. Please note, these parameters affect the calculations directly and may have unexpected side effects. The adjustment values will shift the calculated warping by factor*value. Its main use is like shifting a projector manually

Note

Those properties should be used to adjust the projection manually instead of modifying it on the output device, because changes here will be exported after each autoalignment process.

Global settings

There are some properties that apply to the whole projection system. They can be modified in the settings tabs.

General settings

Use Alignment Data: The most important element is the selector for Alignment data. If true, all further calculations are based on the data from the last auto align process instead of the initial calibration. The button is unavailable as long as there is not alignment data for all projectors stored in the database.
Touch Margin: Allows to globally adjust touch margin for touching channels. See section Touching Channels for further information about high resolution projectors with multiple inputs and touching channels.

Interpolation

Captured calibration data is usually incomplete and captured only for a finite number of points. For exporting correction data, Mappers need to interpolate and extrapolate this data for each pixel of a projector and maybe even beyond. Many mathematical strategies exist for that purpose, all with individual strengths and weaknesses.

For some projects, depending on screen and mapping type, it might be necessary to switch to another interpolation type than the default. This can be done in the global Settings/Interpolation tab.

Interpolations are used for different purposes in the project.

General: For all purposes, if not overridden.
Override 2D: Optional override for interpolations between 2d mapping and projectors (influences the grids seen in 2D view).
Override full Mesh: Optional override for generating full meshes in 3d (influences full mesh visualization in 3D View and some advanced exporters)

Two interpolation types are available.

Polynomial (Default): Gives good generalization of general shape of warping with good exact extrapolation near measured data. Has the tendency to fold and generate wrong results far away from measured data. Has a degree parameter to adjust the complexity of warping. Lower values give better extrapolation results, but less fitting to details and strong curvatures.
Spline: Gives better results for strong warpings and tight radii, or even sharp corners on screen. Generally captures details better, but has less generalization. More relaxed far distance extrapolation. Takes considerable more time to calculate!

Shading

The shading-tab of the project-settings dialog allows to set several global parameters that influence blending and black-level-adjust calculations.

Gamma

Gamma of the projectors. Too high values will result in overexposed blending regions, a value that is too low will result in underexposed blending regions.

Uniformity

Enable automatic global uniformity calculation. Allows to adjust the degree of correction. 100% meaning full uniform brightness as the darkest point in the projection. 50% meaning brightness is reduced for all areas brighter than the medium brightness.

Advanced BLC

Automatic overlap calculation and regarding uniformity information for black level correction calculations. Brightness and contrast settings for each individual projector are used.

Max Overlap

Maximum number of projectors overlapping at any point. Typical is 2 for a linear setup of projectors in one row or 4 for a grid of projectors with multiple lines and rows. (Non Advanced BLC only)

Black level

Projectors typically produce no perfect black. They expose still some light to the screen when the input signal is full black. Black Level describes the amount of light the projector exposes for black images. The corresponding preview can be used to help adjusting this value. (Non Advanced BLC only)

Chip Oversize

Projectors typically expose light to a larger area than the area of addressable pixels. These surrounding parts must be taken into account for black-level calculation. When they are not regarded, the edges of the overlapping areas will become apparently brighter than the adjacent areas.

H/V: Horizontal/vertical oversize. Normalized values relative to channel width/height.
Fade: Compensate for smooth black level spillover typically seen on LCOS projectors. Off by default.
Test: Project dark triangles on each projector, supposed to line up with the borders of overlapping projectors. The preview regards global chip oversize, as well as potential overrides per channel. If there is a gap between triangles and overlapping projector decrease the chip oversize. If triangles are drawn partly on top of overlapping projectors increase chip oversize.

Mapping 3D view

The Mapping 3D view shows how 3D content rendered with virtual cameras is warped for each channel. The warping is represented as a distorted mesh in normalized projector chip coordinates ranging from (0,0) top-left to (1,1) bottom-right.

The red and green edge represent the top and left edge of the projector. The mesh is also colored depending on the estimated quality of the calibration. The quality gradient ranges from blue (very good) over green and yellow to red (bad).

Visualization Options

A drop down menu on the top left corner allows to select multiple visualization options.

Show Source: Shows the source grid.
Show Target: Shows the warped grid.
Show Vector: Visualizes the warping offset for each warping point, rendered as a white connection line between corresponding source and target coordinates.

Navigation

The view can be dragged with the left mouse button.

Scaling

Several scaling options are available at the top right corner of 2D View.

Mapping 2D view

Mapping2d view with one projector (left) or all projectors (right) selected

The Mapping 2D View Shows the texture space, a normalized space ranging from (0,0) top-left to (1,1) bottom-right. It defines how 2d content is mapped onto the screen. This mapping is used for fadeout, clipping and blending calculations.

Selected projectors are shown in this view as a mesh. The mesh represents the region of the texture used for the corresponding projector. The red and green edge represent the top and left edge of the projector. The mesh is also colored depending on the estimated quality of the calibration. The quality gradient ranges from blue (very good) over green and yellow to red (bad).

Visualization Options

A drop down menu on the top left corner allows to select multiple visualization options.

Fadeout: In addition a visualization of the fadeout can be activated. The fadeout start and stop edge is marked by a white and black line. The fadeout can be adjusted in mapping settings, see section Shading for further informations.
UV-Layout: A semi-transparent grid visualizing the area covered by the current mapping. This area is influenced by current mappings uv transform. Especially interesting for “Reference Mesh” mapping. See section Mapping for further information about mappings.

Navigation

The view can be dragged with the left mouse button.

Scaling

Several scaling options are available at the top right corner of 2D View.

3D view

The 3d view window shows the measured screen, mapping visualization and current virtual cammeras in 3d space.

3D view displaying one projector (left) or all projectors (right)

The current selection of projectors, camera position and reference points is regarded. Unselected elements are dimmed or hidden.

Viszalization Options

A drop down menu on the top left corner allows to select multiple visualization options.

Mapping

Represents the current Mapping-settings. It shows the screen-shape and iconic projection-rays at the corners of the screen. In addition the projection of the measured points onto the screen are visualized.

Virtual Cameras

shows a representation of currently setup virtual cameras. The camera frustum is rendered regarding cameras frustum settings and target distance.

Projection

The measured projection can be visualized in three different ways:

Measured Points: 3d-position of measured points.
Measured Mesh: Triangulation of measured points.
Full Mesh: Based on current Measurements, the full projector is reconstructed (unmeasured parts as well).

Perspective

Switch to predefined orthographic views or the default perspective camera position.

Navigation

Navigate the 3d view using the mouse.

Rotate: Left mouse-button
Move: Middle mouse-button, Alt+Shift+LMB
Zoom: Right mouse-button, Alt+Ctrl+LMB

Preview Toolbar

Several quick previews can be shown on physical screen, to assist during setup of blending, fadeout, ramps, mapping and easy camera.

The most often used previews have a button in the Preview Toolbar. Simply press a preview-button to show or update the corresponding preview.

Under some additional previews can be found.

Please note, that many preview images are results of simplified calculations and therefore not perfect. To judge the quality of a calibration a more time consuming preview export or an export into the real imaging system is needed.

Note

For the preview to work a PatternGenerator must be properly installed and running on each display computer. The warping is handled dynamically by PatternGenerator. If installed, warp units should not apply any blending or warping during the preview. Only exception is Preview 3D unwarped, this preview mimics a simple 3d engine where the rest of the correction needs to be done on an external warping solution.

Black

make all projectors black

White

make all projectors full white

Cutting

Visualize, which parts of projectors will be used for projection. Due to intersection of physically projected area and virtual camera frustum, this area can be smaller than the actual projector. Also projector blanking settings can further reduce the area actually projected on.

Warping

Visualize the resulting warping grid based on current virtual camera settings.

Shading

rough shading preview (resolution is depending on projects mesh resolution settings)

Black Level

rough black level adjust preview (resolution is depending on projects mesh resolution settings)

Fadeout

rough preview of current fadeout settings (without blending)

Uniformity

preview of current uniformity correction without blending applied

Rectangular grid

project a rectangular grid using current mapping settings (typically used with Perspective, Planar, Cylindrical or Spherical LongLat mapping)

Polar Grid Half Dome

project a circular grid using current mapping settings (typically used for spherical polar mapping)

Polar Grid Full Dome

project a circular grid using current mapping settings, projects twice as much rings as Half Dome grid. (typically used for spherical polar mapping)

Outlines

Renders all expected outlines using the calibrated system except for selected projectors. Selected projectors have their current real outline rendered and are filled gray. This can be used to put single projectors easily in their correct position after maintenance and before recalibration. Usage:

Select Projector, that has moved.
Preview Outlines.
Adjust physical projector position, orientation, zoom and shift until it fits its rendered outlines as close as possible.
Re-Align the system to get perfect continuous geometry again.

Preview 3D

Render a simple cube map using currently setup virtual cameras. This preview is not warped. Warping on external warping solution must be activated.

Preview 3D warped

Render a simple cube map using currently setup virtual cameras. This preview is already warped. Warping on external warping solution must be deactivated.

Live Warping

Opens an interactive 3D-Preview, where the viewpoint can be modified on the fly. This can be used to check quality and image cut-off for dynamic view-dependent warping.