move generic bpy helper modules into bpy_extras.
[blender-staging.git] / release / scripts / modules / bpy_extras / view3d_utils.py
1 # ##### BEGIN GPL LICENSE BLOCK #####
2 #
3 #  This program is free software; you can redistribute it and/or
4 #  modify it under the terms of the GNU General Public License
5 #  as published by the Free Software Foundation; either version 2
6 #  of the License, or (at your option) any later version.
7 #
8 #  This program is distributed in the hope that it will be useful,
9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11 #  GNU General Public License for more details.
12 #
13 #  You should have received a copy of the GNU General Public License
14 #  along with this program; if not, write to the Free Software Foundation,
15 #  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 #
17 # ##### END GPL LICENSE BLOCK #####
18
19 # <pep8 compliant>
20
21
22 def region_2d_to_vector_3d(region, rv3d, coord):
23     """
24     Return a direction vector from the viewport at the spesific 2d region
25     coordinate.
26
27     :arg region: region of the 3D viewport, typically bpy.context.region.
28     :type region: :class:`Region`
29     :arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
30     :type rv3d: :class:`RegionView3D`
31     :arg coord: 2d coordinates relative to the region;
32        (event.mouse_region_x, event.mouse_region_y) for example.
33     :type coord: 2d vector
34     :return: normalized 3d vector.
35     :rtype: :class:`Vector`
36     """
37     from mathutils import Vector
38
39     dx = (2.0 * coord[0] / region.width) - 1.0
40     dy = (2.0 * coord[1] / region.height) - 1.0
41
42     viewvec = rv3d.view_matrix.inverted()[2].to_3d().normalized()
43     perspinv_x, perspinv_y = rv3d.perspective_matrix.inverted().to_3x3()[0:2]
44     return ((perspinv_x * dx + perspinv_y * dy) - viewvec).normalized()
45
46
47 def region_2d_to_location_3d(region, rv3d, coord, depth_location):
48     """
49     Return a 3d location from the region relative 2d coords, aligned with
50     *depth_location*.
51
52     :arg region: region of the 3D viewport, typically bpy.context.region.
53     :type region: :class:`Region`
54     :arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
55     :type rv3d: :class:`RegionView3D`
56     :arg coord: 2d coordinates relative to the region;
57        (event.mouse_region_x, event.mouse_region_y) for example.
58     :type coord: 2d vector
59     :arg depth_location: the returned vectors depth is aligned with this since
60        there is no defined depth with a 2d region input.
61     :type depth_location: 3d vector
62     :return: normalized 3d vector.
63     :rtype: :class:`Vector`
64     """
65     from mathutils.geometry import intersect_point_line
66     origin_start = rv3d.view_matrix.inverted()[3].to_3d()
67     origin_end = origin_start + region_2d_to_vector_3d(region, rv3d, coord)
68     return intersect_point_line(depth_location, origin_start, origin_end)[0]
69
70
71 def location_3d_to_region_2d(region, rv3d, coord):
72     """
73     Return the *region* relative 2d location of a 3d position.
74
75     :arg region: region of the 3D viewport, typically bpy.context.region.
76     :type region: :class:`Region`
77     :arg rv3d: 3D region data, typically bpy.context.space_data.region_3d.
78     :type rv3d: :class:`RegionView3D`
79     :arg coord: 3d worldspace location.
80     :type coord: 3d vector
81     :return: 2d location
82     :rtype: :class:`Vector`
83     """
84     prj = Vector((coord[0], coord[1], coord[2], 1.0)) * rv3d.perspective_matrix
85     if prj.w > 0.0:
86         width_half = region.width / 2.0
87         height_half = region.height / 2.0
88
89         return Vector((width_half + width_half * (prj.x / prj.w),
90                        height_half + height_half * (prj.y / prj.w),
91                        ))
92     else:
93         return None