ProjectionViz

version 1.0.0

Users Guide

Created by Joshua Benghiat

Getting Started

About

ProjectionViz is a Plug-in object for Vectorworks® allowing for precise calculation and pre-visualization of projector cones. ProjectionViz excels at examining complex scenarios, such as off-axis, irregularly-shaped, or multiple image planes.

The ProjectionViz object displays the projector cone in both Top/Plan and 3D as well as projects a full color image in Renderworks renders.

Installation

The install package is a . vwlibrary file

In Vectorworks, select Tools > Plug-ins > Plug-in Manager
Select the Third-party plug-ins tab
Click the Install… button
Navigate to and select the installer vwlibrary file
Read and confirm the EULA
Vectorworks should notify you that installation is complete and to restart Vectorworks

Adding to Your Workspace

In order to use the ProjectionViz insertion tool, you need to add it to your workspace:

Select Tools>Workspaces>Workspace Editor.
Select the Tools tab.
Click the disclosure triangle next to JBLD in the list of Tools categories on the left hand side.
Drag the all the ProjectionViz Plug-In Object to an existing palette on the right or create a new palette.
Click OK.

Registering

The first time you use ProjectionViz, the software will ask you for a registration number or demo code. You can also access the registration dialog through the “About” button in the Object Info palette with a ProjectionViz object selected. The ProjectionViz objects will not draw without a valid code.

You can use the Request Demo button to enable a fully-functional 30 day demo period.

Inserting a ProjectionViz Object

To insert a new ProjectionViz object, select the tool

You can insert the ProjectionViz object by clicking on the center of the image plane, clicking on the projector location, or by drawing a line between the projector location and the image’s focus point (throw mode).

If you are using the Projector location or Throw modes, you can optionally detect the z height of the object below the first click, like a pipe or truss. This option is particularly useful when inserting in 2D and snapping to a hybrid object.

If you are in Throw mode, inserting in a 3D view allows you to snap to a projector location and focus point. In 2D mode, use the object’s default settings and the Determine focus by mode bar option to set the projector’s initial tilt.

If you know your projector location and need to determine projector specifications

You may find inserting in Throw mode is the easiest option, drawing a line from the projector to the center of the image plane to insert the ProjectionViz cone.

If you know the size of the image you need, towards the top of Object Info, set the Lock size of option to image , and set your desired image size in the Image Plane Options.

If you know the lens you are using, set the Lock size of option to lens , and set your lens ratio under lens and image.

Adjust additional parameters in Object Info to experiment with different projector options.

If you know your projector specifications and need to determine projector location

With the tool selected but before inserting the ProjectionViz object, click the Preferences button in the mode bar.

Set lens ratio, aspect ratio, etc. according to your projector specifications. To calculate the initial throw, next, set the Lock size of option to image , and set your desired image size in the Image Plane Options.

Exit Preferences and set the tool to use Insert at Image Plane mode.

Click in the drawing to set the projector focus, and use a second click to determine the projector pan.

Adjusting the Projection Cone

Using Object Info, you can adjust the following parameters:

X, Y: The object’s location always reports as the image plane focus point
Z: The zero-point from which ProjectionViz measures the focus point. Adjust this value when your focus point uses a different reference than the hanging point, for example when the image plane is on a raised platform.
Rotation: The reference angle from which ProjectionViz measures pan

During interaction:

The following locks affect editing pan, tilt, and throw, as well as moving and rotating

Lock location of:

Projector – the projector location will remain constant

Focus – the projector focus will remain constant

Lock length of:

Throw – the distance between the projector and focus point remain constant. Use this option if you want the ProjectionViz object to behave like a static object when moving or rotating.

Height – the heights of the projector and the center of the image plane remain constant

Plan Distance – the plan distance between the projector and the center of the image plane remain constant

Lock size of:

Lens – the lens ratio remains constant, with the image size adjusting with throw

Image – the image size remains constant, with the lens ration recalculating with the throw. With this option selected, the throw will adjust when you manually adjust the lens ratio parameter.

Projector Location

Hanging Height: The z height of the projector. The Lens to Position parameter allows you to set the rigging point, and not the height of the lens.
Pick up height: Press this button to insert the z height of any object below the projector point into the Hanging Height field
Lens to Position: The offset from the rigging point to the lens, in that direction. A positive value means the lens is below the rigging point. If the projector sits on a platform of a known height, use a negative value.
Projector X / Y: The coordinates of the projector

Projector Focus

Throw: The distance from the lens to the image plane
Throw ∆ X / ∆ Y: The distance along each axis from the projector to the image plane
Cone center height: The height of the center of the image plane. This measurement does not take lens shift into account
Calc Focus Height: Use the resulting dialog to calculate the Cone cone center height based on the reference point and distance you specify. See Setting the Focus Point.
Pan: Degrees from the object’s rotation angle
Tilt: Degree from horizontal. Tilting up is a positive value. The interaction locks have a large effect on how the object tilts
Rotation: Rotate the projector and image around the throw axis. A 90 degree rotation will effectively swap the image ratio, making a vertical image

Keystone / lens shift

H / V Lens shift %: Lens shift affects the location of the image without distorting it. The value is a percentage of the image size, which matches the lens shift limits found in most projector specifications.
Keystone adjust H / V: Keystone adjustment is an electronic function, warping the image and adding wedges of video-black in order to counteract keystone distortions. This value currently only affects rendered images, giving a sense of the required keystone correction for your projector arrangement.

Lens and image

Aspect: Choose a common aspect ratio for the projector image. You can find a reference for aspect ratios here: https://en.wikipedia.org/wiki/Aspect_ratio_(image) . You can also input a custom ratio.
Custom ratio: Enable this option in the pull-down menu above.
Lens: The lens ratio is given in the specification for most projector lenses and is the quotient of the throw over the image width
Spread angle (w): A read-only calculation of the horizontal spread of the image cone
Lumens: The specified lumens of the projector, usually found in the projector specification
Screen gain: Used in calculating the image’s liminance
Luminance: A read only value calculated from the lumens, screen gain, lens, and throw. ProjectionViz displays foot-Lamberts when using standard units and candela per square meter, a.k.a. nit (nt), in metric.

Image plane options

Orientation: Vertical with respect to the ground plane

Horizontal with respect to the ground plane

Perpendicular to the throw
V / H Image Tilt: Further adjust the tilt of the image plane, in degrees
Additional image throw: Visualize an additional image plane based on throw distance. For example, view both the back wall and proscenium planes. When the additional plane is non-zero, you will also see a control point for positioning the image plane.
Show floor: In addition to the main image plane, show where the image will fall on the floor
Max width: The width of the projected image at center
Max height: The height of the image at center
Diagonal: The diagonal measurement of the image

Display Options

Show cone

Draw the sides of the projector cone

Show image plane

Draw the image plane

Show focus vector

Draw a line from the projector to the focus point

Show Focus Point

Display a locus at the focus point. Note, for projections using a lens shift, the focus point is not the center of the image.

Indicate projector

Choose how to display the projector. When the render options are set to project an image, this is always a locus point.

Box

Locus point

Symbol

Select Symbol

When the you select the symbol option above, use this button to choose the symbol

Display projector text

Enable this option to show a text label near the projector

Projector text

Quickly enter a short text note or use for copying and pasting text

Edit

Use a dialog to edit multi-line note text. You can also insert tokens to dynamically display projection parameters and calculations.

Display focus text

Enable this option to show a text label near the focus point

Focus text

Quickly enter a short text note or use for copying and pasting text

Edit

Use a dialog to edit multi-line note text. You can also insert tokens to dynamically display projection parameters and calculations.

Rendering Options

Choose image: Click to choose an image to project or display on the image plane. See Using Your Own Image.
Image Texture: A read only indicator of the projector image. By default, ProjectionViz uses an alignment raster appropriate to your aspect ratio.
Simulate screen image: Places fills the image plane with a texture, simulating a projected image. Vectorworks cannot distort textures, so this will not approximate keystoning. This option is useful for presentation renders on traditional rectangular screens.
Only show image plane: Hide all ProjectionViz geometry except for the image plane. Useful for presentation renders or aligning a projected raster to scenery.
Project image: Project a rendered image. See Projecting Images in 3D

Classes

Auto-Class: Automatically generate and assign classes based on the root class in Settings
Cone: The class of the projection cone
Image plane: The class of the image plane
Focus Vector: The class of the vector from the projector to the image
Text: The class for all text labels

–

View from projector: Set the perspective view to the projector cone
Look to projector: Set the perspective view too look at the projector from the image. Useful for finding an unobstructed location to place the projector.
View section: View the projector cone in section. This makes it easy to work with the projector cone as though it were a flattened section.

–

Add Video Screen Object: Adds a Spotlight Video Screen object with the current ProjectionViz settings. The Video Screen excels at showing screen and projector geometry. Note, the Video Screen’s calculations are not as sophisticated as ProjectionViz, so you will not see the keystoning that ProjectionViz displays.

–

Settings: See ProjectionViz Settings
About: See the current version, enter your registration, and see links to documentation and report a bug

Setting the Focus Point

You have a number of methods to set the projector’s focus point

Move the object with Lock location set to Projector. Moving in Top/Plan adjusts the x / y location of the image plane. Moving in an orthogonal view perpendicular to the ground plane (side, front, etc) changes the projector x / y location and tilt.

With the object selected, grab and move the focus control point

Click the Calc Focus Height button in Object Info

PV Set Focus Height

Enter the measurement

Enter the reference point from where you are measuring

Enter the end point of the measurement

Enter whether you want to achieve the focus height using tilt or lens shift.

Moving and Reshaping

Moving and rotating

When moving and rotating, the ProjectionViz object adjusts its parameters according to the object’s interaction locks. For example, when locked to the projector location and length of heights, nudging the object will adjust the focus point.

Control points

The projector and screen locations each have control points that you can use to reshape the projector throw in both 2D in 3D. When in an orthogonal view perpendicular to the ground plane, moving control points will maintain the projector’s pan.

Working in Section

ProjectionViz works well with the Edit in-place option for Section Viewports, with both of the above options fully functional.

Duplicating ProjectionViz Objects

You can determine how ProjectionViz duplicates via the Settings dialog, accessed at the bottom of Object Info.

When duplicating, lock:

Projector

Duplicating will keep the projector location constant. Useful for trying an alternate focus from the same position.

Focus

Duplicating will keep the projector focus point constant. Useful when doubling a projector on the same image plane.

Neither

Duplicating will keep the projector throw, pan, and tilt constant.

Object’s Mode

Duplicate using the objects Lock options

Projecting Images in 3D

To project a rendered image, enable Project Image in the Rendering Options

OpenGL

OpenGL can only transparent textures in black and white (true black and white, not grayscale). This makes OpenGL a useful tool for live adjustments of raster grid slides or rough images, but not for presentation renders. OpenGL also inverts transparent textures, so any black pixels will be fully transparent and vice versa.

Renderworks

Renderworks allows for full color projected images, though the rendering processing is slower.

Using Default Raster Grids

When you first select the Project Image option, ProjectionViz will import a default raster grid for the selected aspect ratio. The hasted grid is just a typical bitmap image — you can create an import your own image using the below steps.

Using Your Own Image

Select the Choose Image button in Object Info

A new texture

Choose a name for the new texture resource. In the following dialog, select an image to use as the projection slide.

Edit the selected texture

Apply adjustments to the currently selected slide

An existing texture

ProjectionViz creates two textures for every image — one to simulate the screen image without projected light and one to render an actual projection. Always choose the texture WITHOUT the “-slide” suffix.

ProjectionViz Settings

First, either select a ProjectionViz object or, with the ProjectionViz took active, press the Preferences button in the mode bar. You can access behavior settings via the Settings Button at the bottom Object Info.

Default Insertion Class

Choose a class for all new ProjectionViz objects instead with its tool. You can also set this option to <Active Class>

Component class prefix

Enter a prefix that will be added to all sun-classes when using the Auto-Class button. The prefix may be but is not required to be an existing class.

When duplicating, lock:

Projector

Duplicating will keep the projector location constant. Useful for trying an alternate focus from the same position.

Focus

Duplicating will keep the projector focus point constant. Useful when doubling a projector on the same image plane.

Neither

Duplicating will keep the projector throw, pan, and tilt constant.

Object’s Mode

Duplicate using the objects Lock options

Make default for all new documents

Check this box to make the selection options default for any new documents. As with other Vectorworks preferences, this setting only applies to the current user.

Using Object Styles

Object Styles allow the user to have any or all attributes reference a named style, which you can manage and edit in the Resource Manager. Styles allow objects to have uniform parameters, for example ensuring an array of projectors all have the same lens and aspect ratio, as a way to access manufacturer-specific settings, and as a way to set default parameters.

Creating a Style

To create a new style, the easiest way is to set parameters for a ProjectionViz object in the drawing, then go to the style pull-down menu towards the top of Object Info.

Select New Plug-in Style from…

Optionally, choose a folder for the Style. Styles are managed like symbols.

You will see an Object-Info-like dialog, where you can further adjust parameters. At the top of the dialog, you will find options to name the style and to choose which parameters should refer to the style and which can vary per-instance.

Applying a Style

Select the ProjectionViz object to which you want to apply the style.

Towards the top of Object Info, find the Style pull-down menu, and select Replace…

Browse to the object style you want to apply.

Creating Masks

If you have a 3D model, you can use ProjectionViz to estimate masks.

You may want to use the Rendering Options to project a raster grid.

With the ProjectionViz object selected, click the View from projector button towards the bottom of Object Info.
Note: Be default, changing pan or zoom will change your perspective view, misaligning the projector view. If you have added a lens shift to this projector the image may be out of view. To change this behavior, go to File>Document Settings>Document Preferences…. Select the Display tab. Enable Cropped Perspective.
Create a Viewport on a new sheet layer.
You should see the image rectangle for this viewport. Crop the viewport to this rectangle.
You can now export this viewport to an image editor and use the view to create a mask.