cam.bas_relief

cam.bas_relief#

Fabex ‘bas_relief.py’

Module to allow the creation of reliefs from Images or View Layers. (https://en.wikipedia.org/wiki/Relief#Bas-relief_or_low_relief)

Exceptions#

ReliefError

Common base class for all non-exit exceptions.

Functions#

copy_compbuf_data(inbuf, outbuf)

restrict_buffer(inbuf, outbuf)

Restrict the resolution of an input buffer to match an output buffer.

prolongate(inbuf, outbuf)

Prolongate an input buffer to a larger output buffer.

idx(r, c, cols)

smooth(U, F, linbcgiterations, planar)

Smooth a matrix U using a filter F at a specified level.

calculate_defect(D, U, F)

Calculate the defect of a grid based on the input fields.

add_correction(U, C)

solve_pde_multigrid(F, U, vcycleiterations, ...)

Solve a partial differential equation using a multigrid method.

asolve(b, x)

atimes(x, res)

Apply a discrete Laplacian operator to a 2D array.

snrm(n, sx, itol)

Calculate the square root of the sum of squares or the maximum absolute

linear_bcg(n, b, x, itol, tol, itmax, iter, err, rows, ...)

Solve a linear system using the Biconjugate Gradient Method.

tonemap(i, exponent)

Apply tone mapping to an image array.

vert(column, row, z, XYscaling, Zscaling)

Create a single vertex in 3D space.

build_mesh(mesh_z, br)

Build a 3D mesh from a height map and apply transformations.

render_scene(width, height, bit_diameter, ...)

Render a scene using Blender's Cycles engine.

problem_areas(br)

Process image data to identify problem areas based on silhouette

relief(br)

Process an image to enhance relief features.

Module Contents#

exception ReliefError[source]#

Bases: Exception

Common base class for all non-exit exceptions.

copy_compbuf_data(inbuf, outbuf)[source]#
restrict_buffer(inbuf, outbuf)[source]#

Restrict the resolution of an input buffer to match an output buffer.

This function scales down the input buffer inbuf to fit the dimensions of the output buffer outbuf. It computes the average of the neighboring pixels in the input buffer to create a downsampled version in the output buffer. The method used for downsampling can vary based on the dimensions of the input and output buffers, utilizing either a simple averaging method or a more complex numpy-based approach.

Parameters:

  • inbuf (numpy.ndarray) – The input buffer to be downsampled, expected to be a 2D array.

  • outbuf (numpy.ndarray) – The output buffer where the downsampled result will be stored, also expected to be a 2D array.

Returns:

The function modifies outbuf in place.

Return type:

None

prolongate(inbuf, outbuf)[source]#

Prolongate an input buffer to a larger output buffer.

This function takes an input buffer and enlarges it to fit the dimensions of the output buffer. It uses different methods to achieve this based on the scaling factors derived from the input and output dimensions. The function can handle specific cases where the scaling factors are exactly 0.5, as well as a general case that applies a bilinear interpolation technique for resizing.

Parameters:

  • inbuf (numpy.ndarray) – The input buffer to be enlarged, expected to be a 2D array.

  • outbuf (numpy.ndarray) – The output buffer where the enlarged data will be stored, expected to be a 2D array of larger dimensions than inbuf.

idx(r, c, cols)[source]#
smooth(U, F, linbcgiterations, planar)[source]#

Smooth a matrix U using a filter F at a specified level.

This function applies a smoothing operation on the input matrix U using the filter F. It utilizes the linear Biconjugate Gradient method for the smoothing process. The number of iterations for the linear BCG method is specified by linbcgiterations, and the planar parameter indicates whether the operation is to be performed in a planar manner.

Parameters:

  • U (numpy.ndarray) – The input matrix to be smoothed.

  • F (numpy.ndarray) – The filter used for smoothing.

  • linbcgiterations (int) – The number of iterations for the linear BCG method.

  • planar (bool) – A flag indicating whether to perform the operation in a planar manner.

Returns:

This function modifies the input matrix U in place.

Return type:

None

calculate_defect(D, U, F)[source]#

Calculate the defect of a grid based on the input fields.

This function computes the defect values for a grid by comparing the input field F with the values in the grid U. The defect is calculated using finite difference approximations, taking into account the neighboring values in the grid. The results are stored in the output array D, which is modified in place.

Parameters:

  • D (ndarray) – A 2D array where the defect values will be stored.

  • U (ndarray) – A 2D array representing the current state of the grid.

  • F (ndarray) – A 2D array representing the target field to compare against.

Returns:

The function modifies the array D in place and does not return a

value.

Return type:

None

add_correction(U, C)[source]#
solve_pde_multigrid(F, U, vcycleiterations, linbcgiterations, smoothiterations, mins, levels, useplanar, planar)[source]#

Solve a partial differential equation using a multigrid method.

This function implements a multigrid algorithm to solve a given partial differential equation (PDE). It operates on a grid of varying resolutions, applying smoothing and correction steps iteratively to converge towards the solution. The algorithm consists of several key phases: restriction of the right-hand side to coarser grids, solving on the coarsest grid, and then interpolating corrections back to finer grids. The process is repeated for a specified number of V-cycle iterations.

Parameters:

  • F (numpy.ndarray) – The right-hand side of the PDE represented as a 2D array.

  • U (numpy.ndarray) – The initial guess for the solution, which will be updated in place.

  • vcycleiterations (int) – The number of V-cycle iterations to perform.

  • linbcgiterations (int) – The number of iterations for the linear solver used in smoothing.

  • smoothiterations (int) – The number of smoothing iterations to apply at each level.

  • mins (int) – Minimum grid size (not used in the current implementation).

  • levels (int) – The number of levels in the multigrid hierarchy.

  • useplanar (bool) – A flag indicating whether to use planar information during the solution process.

  • planar (numpy.ndarray) – A 2D array indicating planar information for the grid.

Returns:

The function modifies the input array U in place to contain the final

solution.

Return type:

None

Note

The function assumes that the input arrays F and U have compatible shapes and that the planar array is appropriately defined for the problem context.

asolve(b, x)[source]#
atimes(x, res)[source]#

Apply a discrete Laplacian operator to a 2D array.

This function computes the discrete Laplacian of a given 2D array x and stores the result in the res array. The Laplacian is calculated using finite difference methods, which involve summing the values of neighboring elements and applying specific boundary conditions for the edges and corners of the array.

Parameters:

  • x (numpy.ndarray) – A 2D array representing the input values.

  • res (numpy.ndarray) – A 2D array where the result will be stored. It must have the same shape as x.

Returns:

The result is stored directly in the res array.

Return type:

None

snrm(n, sx, itol)[source]#

Calculate the square root of the sum of squares or the maximum absolute value.

This function computes a value based on the input parameters. If the tolerance level (itol) is less than or equal to 3, it calculates the square root of the sum of squares of the input array (sx). If the tolerance level is greater than 3, it returns the maximum absolute value from the input array.

Parameters:

  • n (int) – An integer parameter, though it is not used in the current implementation.

  • sx (numpy.ndarray) – A numpy array of numeric values.

  • itol (int) – An integer that determines which calculation to perform.

Returns:

The square root of the sum of squares if itol <= 3, otherwise the

maximum absolute value.

Return type:

float

linear_bcg(n, b, x, itol, tol, itmax, iter, err, rows, cols, planar)[source]#

Solve a linear system using the Biconjugate Gradient Method.

This function implements the Biconjugate Gradient Method as described in Numerical Recipes in C. It iteratively refines the solution to a linear system of equations defined by the matrix-vector product. The method is particularly useful for large, sparse systems where direct methods are inefficient. The function takes various parameters to control the iteration process and convergence criteria.

Parameters:

  • n (int) – The size of the linear system.

  • b (numpy.ndarray) – The right-hand side vector of the linear system.

  • x (numpy.ndarray) – The initial guess for the solution vector.

  • itol (int) – The type of norm to use for convergence checks.

  • tol (float) – The tolerance for convergence.

  • itmax (int) – The maximum number of iterations allowed.

  • iter (int) – The current iteration count (should be initialized to 0).

  • err (float) – The error estimate (should be initialized).

  • rows (int) – The number of rows in the matrix.

  • cols (int) – The number of columns in the matrix.

  • planar (bool) – A flag indicating if the problem is planar.

Returns:

The solution is stored in the input array x.

Return type:

None

tonemap(i, exponent)[source]#

Apply tone mapping to an image array.

This function performs tone mapping on the input image array by first filtering out values that are excessively high, which may indicate that the depth buffer was not written correctly. It then normalizes the values between the minimum and maximum heights, and finally applies an exponentiation to adjust the brightness of the image.

Parameters:

  • i (numpy.ndarray) – A numpy array representing the image data.

  • exponent (float) – The exponent used for adjusting the brightness of the normalized image.

Returns:

The function modifies the input array in place.

Return type:

None

vert(column, row, z, XYscaling, Zscaling)[source]#

Create a single vertex in 3D space.

This function calculates the 3D coordinates of a vertex based on the provided column and row values, as well as scaling factors for the X-Y and Z dimensions. The resulting coordinates are scaled accordingly to fit within a specified 3D space.

Parameters:

  • column (float) – The column value representing the X coordinate.

  • row (float) – The row value representing the Y coordinate.

  • z (float) – The Z coordinate value.

  • XYscaling (float) – The scaling factor for the X and Y coordinates.

  • Zscaling (float) – The scaling factor for the Z coordinate.

Returns:

A tuple containing the scaled X, Y, and Z coordinates.

Return type:

tuple

build_mesh(mesh_z, br)[source]#

Build a 3D mesh from a height map and apply transformations.

This function constructs a 3D mesh based on the provided height map (mesh_z) and applies various transformations such as scaling and positioning based on the parameters defined in the br object. It first removes any existing BasReliefMesh objects from the scene, then creates a new mesh from the height data, and finally applies decimation if the specified ratio is within acceptable limits.

Parameters:

  • mesh_z (numpy.ndarray) – A 2D array representing the height values for the mesh vertices.

  • br (object) – An object containing properties for width, height, thickness, justification, and decimation ratio.

render_scene(width, height, bit_diameter, passes_per_radius, make_nodes, view_layer)[source]#

Render a scene using Blender’s Cycles engine.

This function switches the rendering engine to Cycles, sets up the necessary nodes for depth rendering if specified, and configures the render resolution based on the provided parameters. It ensures that the scene is in object mode before rendering and restores the original rendering engine after the process is complete.

Parameters:

  • width (int) – The width of the render in pixels.

  • height (int) – The height of the render in pixels.

  • bit_diameter (float) – The diameter used to calculate the number of passes.

  • passes_per_radius (int) – The number of passes per radius for rendering.

  • make_nodes (bool) – A flag indicating whether to create render nodes.

  • view_layer (str) – The name of the view layer to be rendered.

Returns:

This function does not return any value.

Return type:

None

problem_areas(br)[source]#

Process image data to identify problem areas based on silhouette thresholds.

This function analyzes an image and computes gradients to detect and recover silhouettes based on specified parameters. It utilizes various settings from the provided br object to adjust the processing, including silhouette thresholds, scaling factors, and iterations for smoothing and recovery. The function also handles image scaling and applies a gradient mask if specified. The resulting data is then converted back into an image format for further use.

Parameters:

br (object) – An object containing various parameters for processing, including: - use_image_source (bool): Flag to determine if a specific image source should be used. - source_image_name (str): Name of the source image if use_image_source is True. - silhouette_threshold (float): Threshold for silhouette detection. - recover_silhouettes (bool): Flag to indicate if silhouettes should be recovered. - silhouette_scale (float): Scaling factor for silhouette recovery. - min_gridsize (int): Minimum grid size for processing. - smooth_iterations (int): Number of iterations for smoothing. - vcycle_iterations (int): Number of iterations for V-cycle processing. - linbcg_iterations (int): Number of iterations for linear BCG processing. - use_planar (bool): Flag to indicate if planar processing should be used. - gradient_scaling_mask_use (bool): Flag to indicate if a gradient scaling mask should be used. - gradient_scaling_mask_name (str): Name of the gradient scaling mask image. - depth_exponent (float): Exponent for depth adjustment. - silhouette_exponent (int): Exponent for silhouette recovery. - attenuation (float): Attenuation factor for processing.

Returns:

The function does not return a value but processes the image data and

saves the result.

Return type:

None

relief(br)[source]#

Process an image to enhance relief features.

This function takes an input image and applies various processing techniques to enhance the relief features based on the provided parameters. It utilizes gradient calculations, silhouette recovery, and optional detail enhancement through Fourier transforms. The processed image is then used to build a mesh representation.

Parameters:

br (object) – An object containing various parameters for the relief processing, including: - use_image_source (bool): Whether to use a specified image source. - source_image_name (str): The name of the source image. - silhouette_threshold (float): Threshold for silhouette detection. - recover_silhouettes (bool): Flag to indicate if silhouettes should be recovered. - silhouette_scale (float): Scale factor for silhouette recovery. - min_gridsize (int): Minimum grid size for processing. - smooth_iterations (int): Number of iterations for smoothing. - vcycle_iterations (int): Number of iterations for V-cycle processing. - linbcg_iterations (int): Number of iterations for linear BCG processing. - use_planar (bool): Flag to indicate if planar processing should be used. - gradient_scaling_mask_use (bool): Flag to indicate if a gradient scaling mask should be used. - gradient_scaling_mask_name (str): Name of the gradient scaling mask image. - depth_exponent (float): Exponent for depth adjustment. - attenuation (float): Attenuation factor for the processing. - detail_enhancement_use (bool): Flag to indicate if detail enhancement should be applied. - detail_enhancement_freq (float): Frequency for detail enhancement. - detail_enhancement_amount (float): Amount of detail enhancement to apply.

Returns:

The function processes the image and builds a mesh but does not return a

value.

Return type:

None

Raises:

ReliefError – If the input image is blank or invalid.