face2FACE documentation

The main add-on shortcut (which by default is F7 , but you can change it in the add-ons preferences section) will be used to create or reactivate projections depending on the selection context.

Creating new projections

To create a new projection you need at least two objects selected. Where the active object will be the target object and all other selected ones gonna be source objects.

Pressing the add-on shortcut key in this state will project the cone onto the cube

The cone and the cube will be projected onto the icosphere

A source objects needs exactly one face to be selected. The target object needs at least one face selected.

The source objects (normally copys of it) where then projected in a way that their selected face will be placed face to face onto each of the target faces.

One face selected in the source cone and one in the target cube

One face selected in the source cone and multiple faces in the target cube

One face selected in each source (cone and star) and multiple faces in the target icospehre

Auto switching source and target

If its clear from the context which one of the selected objects should be the target object (only one has multiple faces selected and all others have one face selected). And it is not the active one. Then it is set automagically to the active object becoming the target. Can be turned off in the usability settings

Creation settings

When creating projections you can influence them by some settings. They can be found in the add-ons n-panel settings under the functional tab.

You can choose if the projected objects are linked (sharing the same mesh data) or are separate individual objects. You also have the possibility to choose the alignement of the objects.

Have a look at the settings section for further details.

Reactivating former projections

When only one object is selected and it is part of a former projection. Then the former projection gets reactivated when pressing the main add-on shortcut key(by default F7).

It is possible that the object is part of multiple projections. Then if the object is target object of an projection then this will be the reactivated projection. In case it belongs to several projection but is itself no target the the first one is choosen

Former projections can also be reactivated in the add-ons n-panel.

This add-on works as an modal operator, which means that things can done in different ways and orders. An can be altered, changed and tweaked during excecution. (By the way it is also possible to pick your work up again and alter it after you aplied your projections) This is done inside the different modal states.

IDLE state

After creating or reactivating a projection you start in the idle state. From here you can reach the all the different transform states:

G - enters the GRABBING state.
S - enters the SCALING state.
R - enters the ROTATING state

Or do some operations which will act on all transformations at once (All other states also have this option, but for the corresponding transform only):

A - adopts the scaling, rotating and the offset from the active object for all the other selected object.
O - resets all transformations to all selected objects into its original state .
D - duplicate the selected object and its sub-projections.
M - mirror the selected object and its sub-projections.
CTRL+N - split the selected objects into a new projection.
W - switch/scroll through the projections.

Or use the selection possibilities which were available globally in each of the states.

You can also alter the view in each state based on your personal settings as long as they did not conflict with the shortcuts of the modal operator. This is the case for example if you have, for some cumbersome reason, set your view pan to the S key. Then the modal will consume the event and your view settings wont work anymore.

After you have tweaked the projection inside the different states in a way you like, you can apply them and leave the modal operaror. Or abort what you have done and return to the state before you started:

Leaving modal operator with apply or cancel

When you are ready with projection you can apply it if youre happy with the results or cancel everything otherwise.

How this is done depends on the usability setting - exit with pie menu (Which by default is on). And also it depends on your are using RIGHT CLICK SELECT or LEFT CLICK SELECT.

if exit with pie menu is set (default) and you are using RIGHT CLICK SELECT:

LEFT MOUSE BUTTON or RETURN - apply changes (holds for all the states).
DRAG WITH RIGHT MOUSE BUTTON or ESCAPE - abort changes (only holds for idle state).

if exit with pie menu is set (default) and you are using LEFT CLICK SELECT:

DRAG WITH LEFT MOUSE BUTTON or RETURN - apply changes (only holds for idle state).
RIGHT MOUSE BUTTON or ESCAPE - abort changes (holds for all the states).

if exit with pie menu is NOT set:

LEFT MOUSE BUTTON or RETURN - apply changes (holds for all the states).
RIGHT MOUSE BUTTON or ESCAPE - abort changes (holds for all the states).

GRABBING state

This is the state in which you can change the position of the projected objects (or in other words the offset to their projection points on the target faces).

It can be done by just moving the mouse around. Than the active object will be placed on the XY plane in account to the view. And all other selected objects will then placed depending on the mode respectively on their target face plane.

R/A - toggles the positioning modes from RELATIVE to ABSOLUTE positioning.
L - toggles the LIMIT mode on and off. If activated the changes can only applied if the projected source face stays inside the bounds of the target face. It it is always on in RELATIVE mode.
X/Y/Z - constrains the transform to a specific axis.
ALT+(1-9) position by a precise offset entered on the keyboard in a way that is common in blender. Can be constrained on the X or Y axis.

Adapt and recenter

A - adopts the offset from the active object for all the other selected objects.
O - resets the offset of all selected objects into its original state .

Positioning modes: RELATIVE vs ABSOLUTE positioning

During absolute positioning the offset of the other selected objects is exactly the same as from the active manipulated object.

While relative positioning takes the size of the target faces into account. And positions all other selected objects relative to the active manipulated object using barycentric coordinates.

In the example you see that the different sizes of target faces lead by absolute positioning not to the desired result. So relative positioning is choosen here.

Leaving the GRABBING state

Leaving will get back into idle state wether you apply your changes or discard them.

LEFT MOUSE BUTTON or RETURN - apply changes.
RIGHT MOUSE BUTTON or ESCAPE - abort changes.

SCALING state

This state as the name suggest is for altering the scale of the projected objects. Again it can be achieved by moving the mouse. Moving to the right increases the scale while moving to the left decreases.

E - stretch the scale so the source faces are fitting into their target faces evenly (which means all object are scaled with the same factor. So when the target faces have different sizes only the smallest will fit). Can be constrained to X or Y axis.
I - stretch the scale so the source face fits into its target face individualy (which means that the scale factor for each object will be adjusted in a way that the faces all fit individually). Can be constrained to X or Y axis.
V - enter mode to edit the variation scale strength (which affects how much random variation each objects scale has).

The value is increased by moving the mouse to right and decreased to left.

Pressing V again reshuffles the random variation scale value for each selected object.

The maximum value for the variable can be edited in the settings
R - enter mode to edit the relative scale strength (which affects how much the target face size is taken into account).

The value is increased by moving the mouse to right and decreased to left.

The maximum value for the variable can be edited in the settings
L - toggles the limit mode on and off. If activated the changes can only applied if the projected source face stays inside the bounds of the target face. It it is always on in RELATIVE mode, because the relative point can only be computed inside the face bounds.
X/Y/Z - constrains the scaling to a specific axis.

Adapt and reset

A - adopts the scaling from the active object for all the other selected objects.
O - resets the scaling of all selected objects into its original state .

Leaving the SCALING state

Leaving will get back into idle state wether you apply your changes or discard them.

LEFT MOUSE BUTTON or RETURN - apply changes.
RIGHT MOUSE BUTTON or ESCAPE - abort changes.

ROTATING state

And last but not least the state for altering the rotation of the projected objects. Moving the mouse to the right rotates in clockwise direction and moving to the left the other way round.

V - enter mode to edit the variation rotation strength (which affects how much random variation each objects rotation has).

The value is increased by moving the mouse to right and decreased to left.

Pressing V again reshuffles the random variation rotation value for each selected object.

The maximum value for the variable can be edited in the settings
I - toggle the rotation direction between counter- and clockwise.

Aligning

E - align a fixed target face edge with one of the source face edges.
ALT+E - align a fixed source face edge with one of the target face edges.
SHIFT+E - counterclockwise align a fixed target face edge with one of the source face edges.
SHIFT+ALT+E - counterclockwise align a fixed source face edge with one of the target face edges.
SHIFT+ALT+E - counterclockwise align a fixed source face edge with one of the target face edges.

Rotate by fix step angles

-> - rotate in steps around a fixed angle in clockwise direction.
<- - rotate in steps around a fixed angle in counter-clockwise direction.
ALT+->or<- - rotate in steps around an alternative fixed angle
SHIFT+->or<- - rotate in steps around an alternative fixed angle
CTRL+->or<- - rotate in steps around an alternative fixed angle

Precise

ALT+(1-9) rotate around a precise angle entered on the keyboard in a way that is common in blender.

Adapt and reset

A - adopts the rotation from the active object for all the other selected objects.
O - resets the rotation of all selected objects into its original state .

Leaving the ROTATING state

Leaving will get back into idle state wether you apply your changes or discard them.

LEFT MOUSE BUTTON or RETURN - apply changes.
RIGHT MOUSE BUTTON or ESCAPE - abort changes.

Project projections

You are able to use former projections for new ones. So you can take an target object with all its projected objects and use it as a source for the next projection.

You can redo this with the new created projection and project it again with all its subprojection.

All this keeps the sub projections intact so you can alter them again afterwards when needed.

Allowing for complex tweakable structures.

Projections and booleans

Of course you can use your projections in combination with all the different boolean modifiers.

And if you project a projection with a boolean on an sub-object, the boolean target will be correctly set to the new projected objects. This also applies for objects duplicated inside a projection.

Show Projections

If You wanna know which projections exists in the scene and which objects belongs to a specific projection. Then have a quick look in the projections panel under the scene tab.

You have the option for each projection to select all objects, just the target object or just the projected ones.

This helps you to keep track of your projections.

Deleting Projections

In the projections panel under the active tab you see all the projections in which the currently active objects is involved. Either as a target or just as part of the projected objects.

You have possibility to delete each of those projections by clicking on the red x-button.

Furthermore, you can also delete multiple projections. Select each by checking them in the radio box on the top-left. And to delete the selected you click on
delete selected projections beneath the listed projections.

Copy Projections

In this panel You can also copy whole projections. This copies all involved objects creates a new projection collection(s) and also the meta-data for the new projection(s).

Join Projections

You can also join the selected projections into one. In the dropdown you can choose which projection will be the remaining one. This also means that the values which count for each projection like for example the random variation scale/rotation are the ones which are taken from that projection.

Removing selected projected objects

In the projections panel under the selected tab you have can either remove them from their projection. Just removing the projection meta-data, while keeping the objects.

Or to completely delete the objects with all their possible sub-objects (projected objects of their own projections all the way down the hierachy).

Duplicating projected objects

Simply press the D key in the idle state and the selected projected objects will be duplicated, making them part of the projection.

The new copied objects will get the same target face and all the other attributes from the original ones.

You will automatically switch to grab mode to position the new objects, like you are used to when copying objects the normal way.

Splitting Projections

In the idle state the selected projected objects can be splitted into a new projection of the target object. The new projection takes the projection specific attributes from the projection they were split off.

Switching projections

If the target object of the current projection has multiple projections, then you are able to scroll through them in the idle state.

Just press the W key and use the mousewheel afterwards.

And switch to another projection without leaving the modal.

This gives you quick accces to all other projections sharing the same target object.

SELECTION possibilities

Selections of the projected objects can be done in various ways. For example with an imitated box, circle and single object selection similar to the normal blender ones. But also by object type, target face type or for example objects on the same face loop. Some shortcuts here depend on whether you have RIGHT CLICK SELECT or LEFT CLICK SELECT enabled. So we will write in the following about
SELECTIVE MOUSE BUTTON and CANCELING MOUSE BUTTON,
which means depending on your choice:
RIGHT MOUSE BUTTON or LEFT MOUSE BUTTON.

single object selection

This depends on the usability setting exit with pie menu. If it is set true the selection behavior is the same as you are used to in blender except that it only selects out of the set of the projected objects.

Otherwise, if it is set to false then, instead of the common behavior in blender you have to press also alt for selecting a single object. This is because the SELECTIVE MOUSE BUTTON is already used for applying or canceling the operations of the state.

with exit with pie menu set:
SELECTIVE MOUSE BUTTON- just select the object clicked on and deselect the others.

without ~~exit with pie menu~~ set:
ALT+SELECTIVE MOUSE BUTTON- just select the object clicked on and deselect the others.
SHIFT+SELECTIVE MOUSE BUTTON- toggle the selection of the object clicked on.

box selection mode

With the usability setting exit with pie menu set and right click select it should be like the common behavior in blender. Otherwise you have to press B in advance to enter the mode.

B - enters the box selection mode.

LEFT MOUSE BUTTON - drag a box around the objects which should be additionally selected.
SHIFT+LEFT MOUSE BUTTON - drag a box around the objects which should be deselected.
RIGHT MOUSE BUTTON or ESCAPE - for leaving the mode.

circle selection mode

Should be like the common behavior in blender.

C - enters the circle selection mode.

LEFT MOUSE BUTTON - objects inside the circle are additionally selected.
SHIFT+LEFT MOUSE BUTTON - objects inside the circle are desecleted.
WHEEL UP - increases the circle size.
WHEEL DOWN - decreases the circle size.
RIGHT MOUSE BUTTON or ESCAPE - for leaving the mode.

target face type selection mode

Select objects based on their target face type (which is simply the amount of vertices. Tris, quads, n-gons).

ALT+1 select all objects.
(3-9) select all objects of the same type and deselect the others.
SHIFT+(3-9) select all objects of the same type additionally to the current selection.
CTRL+(3-9) deselect all objects of the same type from the current selection.

object type selection mode

This is the possibility to select objects based on their type (which means they share the same source object).

T - enters the type selection mode.

SELECTIVE MOUSE BUTTON - select all the objects of the same type.
SHIFT+SELECTIVE MOUSE BUTTON - select them additionally to the current selection.
CTRL+SELECTIVE MOUSE BUTTON - deselect them from the current selection.
CANCELING MOUSE BUTTON or ESCAPE - for leaving the mode.

face loop selection mode

This is the possibility to select objects which share the same face loop. It is only possible when the target faces are quads.

F - enters the face loop selection mode.

SELECTIVE MOUSE BUTTON - select all the objects on one of the face loops.
ALT+SELECTIVE MOUSE BUTTON - select all the objects on the other face loop.
SHIFT+SELECTIVE MOUSE BUTTON - select them additionally to the current selection.
ALT+SHIFT+SELECTIVE MOUSE BUTTON - select them additionally on the other face loop.
CTRL+SELECTIVE MOUSE BUTTON - deselect them from the current selection.
ALT+CTRL+SELECTIVE MOUSE BUTTON - deselect them on the other face loop.
CANCELING MOUSE BUTTON or ESCAPE - for leaving the mode.

reset transforms into its original state

The transform will be reset to its state at the start of the modal operator right after their projections. Deleting all changes ever made. If you want just to undo the currently changes done in a specific transform state like grab, scale or rotate just leave the state with RIGHT MOUSE BUTTON or ESCAPE.

Fast Snap Mode

By pressing the alternative add-on shortcut (which by default is ALT+F7 , but you can change it in the add-ons preferences section), with one object and a single face selected, you enter the fast snap mode. Which just quickly setups the snap settings in blender to snap to a face, adjust the object origin and orientation and enters the grab mode. So you can snap objects face2FACE in just a single click (Given the face is already selected).

Warning other than the normal face2FACE projections this will change the object origin permanently at the moment (planned to be changed in later versions).

Settings

With the help of the settings you can change the face2FACE add-on to fit your needs. We have global settings which can be found in the blender preferences. They will count for each new created session. And there are local settings which can be found in the 3D View N-Panel under the f2F add-ons Tab. They will only be saved in the specific file and used when file is loaded with such altered settings.

functional

Settings altered in this section are changing the face2Face projection behavior.

Creation

Settings which influences the created projections.

linked_copy - Decides whether the projected objects are sharing their data or not.

linked_from_source - if linked copy is enabled you can decide if the projected objects are linked from the source object data or if they are separately linked.

copy_when_single_target - when only 1 target face is selected you may directly project the source object.

Creation - start alignment

The start alignment of the projected objects can be set in such a way, that all the projected objects are aligning to a specific edge of their target faces. This can be the edge with the highest or lowest value for one of three global axis. Alternatively the alignment edge can be determined by the longest or the shortest size.

Delete projections

Settings which will determ how to delete projections.

delete subs also - determs whether the sub-projections should be deleted with the main-projection.
delete objects also - if enabled the view will be set aligned to the currently active object.
delete target object also - visualize the none selected objects of the projection.

delete other projections also - delete all other projections with the target object also.
delete childs also - determs whether with the target object its childs should also be deleted.

Alter projections

Settings which will determ how to alter projections.

transform sub-projections - determs whether sub-projections should be altered/transformed together with the main-projection. Normally this should be on, turning off only makes sense if have a projection without sub-projections. Then you can get a performance gain.
limit full face - limit transforms by full face or midpoint only.

Max scale variation

max scale variation strength - set the maximum scale variation. Determs a range of variation.
max scale relative strength - set the maximum relative strength. Determs how much the target face size is taken into account.

Step size for variation

This can be useful for for example if you have buildings and want to project them randomly on a square plane. you can restrict the variation to 90 degree. And the buildings will stick straight to the streets. TODO: insert example pics

vary rotation step - set the step size for the random rotation variation.
vary scale step - set the step size for the random scale variation.

usability

Settings which only alter the user experience.

Start options

start with relative_pos - choose whether you will start with relative or absolute positioning mode.
start with limit - choose to limit grab movement in the borders of the target face
(only works in absolute positioning mode).
switch source and target when mixed up - Switch source and target when face count hints that they are mixed up. relative or absolute positioning mode.
exit with pie menu - Safely exit with a pie menu to avoid quickly wrong decisions. Also enables usual selection without alt.
(only works in absolute positioning mode).

Step rotation angles

Here you can set the size of the fixed angles at which the projected objects can be rotated via shortcut. The shortcuts can used together, which will add up the angles. For example:

SHIFT + CTRL+-> = shift_rotation_step + ctrl_rotation_step = 5° + 15° = 20°

shift rotation step - a fixed rotation angle (default 5°) triggered by shortcut
ctrl rotation step - a fixed rotation angle (default 15°) triggered by shortcut
normal rotation step - a fixed rotation angle (default 30°) triggered by shortcut
alt rotation step - a fixed rotation angle (default 45°) triggered by shortcut

visual

auto view - if enabled the view will be set aligned to the currently active object.
highlight projected_objects - visualize the none selected objects of the projection.
highlight rotation_flipped - visualize selected objects which rotation direction is flipped.
show logo - show or hide the face2FACE logo.

The color theme should be self explainable. Just pick your favorite colors.

integrity

Settings for internal projection integrity checks. These checks are done at several occasions. First when loading a file, before creating or reactivating a projection. Or when objects involved in projections are deleted for example. And depending on the settings steps may be taken to keep the integrity by fixing projections or to delete projections.

Auto delete projections

auto delete no target - during integrity check: auto delete projection if it has no target object.
auto delete no belongings - during integrity check: auto delete projection if it has no projected objects.

Auto fix projections

create collections - during integrity check: create collections if they do not exists.
remove objects outside collections - during integrity check: delete objects if they are outside of the projection collection.
integrity move objects outside collections - during integrity check: move objects if they are outside of the projection collection.

Objects without target face

integrity remove objects without target - during integrity check: remove objects if they are without target face.
integrity assign2nearest without target - during integrity check: assign objects 2 nearest face if they are without target face.

Objects without source face

remove objects without source - during integrity check remove objects if they are without source face.

logging

The steps taken by the internal integrity checks are logged and the last logs can be read afterwards.

They contain sometimes hint-buttons which let you select the objects moved back into the projection collection. Or the remaining objects of deleted projection for example.

Errors are shown in red and fixing actions in green.

changelog

Version 0.81

Bugfix: Addressing changes in bleeding edge 3.0 alpha.
Bugfix: Prevent undo to throw error if addon was not activated.
Plus minor ui changes.

Version 0.80

Bugfix for mac-os to obey strict shader code

Version 0.79

It is now possible to project objects with geometry nodes modifiers attached properly. Which means if an attached geometry modifier contains objects from the projection hierachy (The projected object itself or its childs) then the modifiers of the projected copys reflect now the new copied objects.
bugfix: When deleting projections delete the childs get deleted also(again was broken due to some changes)
bugfix: Copyingy projections via the button under active tab when the active object is a projected one now functions correctly.
Also done some more internal changes to make the addon future-proof for for upcoming changes in 3.0

Version 0.78

This contains a critical bugfix for everyone using bleeding edge Blender alpha 3.0. There were some recent changes in the blender python api which have broken the add-on. So if you are using latest Blender experimental version then please update to this version to fix it.

Documentation

Content overview

Requirements

Installation

How to update

Lets get started

Activating Prequesites

Creating new projections

Auto switching source and target

Creation settings

Reactivating former projections

The different modal states

IDLE state

Leaving modal operator with apply or cancel

GRABBING state

Adapt and recenter

Positioning modes: RELATIVE vs ABSOLUTE positioning

Leaving the GRABBING state

SCALING state

Adapt and reset

Leaving the SCALING state

ROTATING state

Aligning

Rotate by fix step angles

Precise

Adapt and reset

Leaving the ROTATING state

Project projections

Projections and booleans

Show Projections

Deleting Projections

Copy Projections

Join Projections

Removing selected projected objects

Duplicating projected objects

Splitting Projections

Switching projections

SELECTION possibilities

single object selection

box selection mode

circle selection mode

target face type selection mode

object type selection mode

face loop selection mode

reset transforms into its original state

Fast Snap Mode

Settings

functional

Creation

Creation - start alignment

Delete projections

Alter projections

Max scale variation

Step size for variation

usability

Start options

Step rotation angles

visual

integrity

Auto delete projections

Auto fix projections

Objects without target face

Objects without source face

logging

changelog

Version 0.81

Version 0.80

Version 0.79

Version 0.78