3D-sdtool - 3D Shape Distribution Tool

Authors:	John Kay Gilberto Galvis
Email:	[email protected], [email protected]
Version:	0.1.1

This project provides a toolkit for handling 3D shapes distributed in a three-dimensional space.

Requirements

• MatLab: The interface tool is based on MatLab, so it is required to have MatLab installed

Installation

• Clone this repository on your machine either using http or ssh

Usage

We really have two tools, which define the approach to using the toolkit: 1) 3D image generation and 2) 3D scenario reconstruction

3D image generation

Having the shape_placement_3D function we can generate a cloud of points that build a series of randomly distributed 3D shapes throughout the three-dimensional space.

Example

Here is an example that can be executed using a MatLab script or also directly in the MatLab Command Window.

% matlab window clean
clc; close all; clear all;

% parameters
polyshape = {'ht', [12, 4, 8, 16], [2, .5, .5, 2.5]};
imsize = [200, 200];
distparams = [14, 8, 6, 22];

% run the function
[img, pitchs, ws, hs] = shape_placement_3D(imsize, polyshape, distparams);

% show the 3D image generated
X = img(:,:,1);
Y = img(:,:,2);
Z = img(:,:,3);

figure()
surf(X, Y, Z); hold on
imagesc(X(:), Y(:), X);

xlabel('X')
ylabel('Y')
zlabel('Z')
xlim([0 200])
ylim([0 200])

Please feel free to change the parameters to the values you want

3D scenario reconstruction

In this case, we start from a three-dimensional scenario with 3D shapes already randomly distributed in space, which was generated by some previous process and whose point cloud is stored in a text file with an .sdf extension. This file has a defined structure with a particular header and body (you can find examples in the inputs folder). Then, the purpose of this second mode of use is to reconstruct that scenario from an intelligent detection of the shape distribution parameters in the real scenario and the generation of a 3D image with those estimated parameters.

Example

Below we show an example of reconstruction. Again, this can be executed using a MatLab script (such as the run_test.m script placed in this repository) or also directly in the MatLab Command Window.

First, we read the real 3D scenario of an .sdf file using the read_sdf. Note that we define a work domain, because the scenario is very large and we only want to concentrate on a small region to better visualize.

% matlab window clean
close all; clc

% read the original point cloud
filename = 'inputs/test_JP2.sdf'; % file name
[Xg,Yg,Zg] = read_sdf(filename);  % read the file
no = 450; nx = 650; ny = 650;     % work domain
Xsurf = Xg(no:ny, no:nx);
Ysurf = Yg(no:ny, no:nx);
Zsurf = Zg(no:ny, no:nx);

Then we detect the shape distribution parameters using the get_3D_pattern_statistics function.

[polyshape, distparams, imsize, features] = get_3D_pattern_statistics(Zsurf, pattype);

Finally, we use the estimated distribution parameters to generate a cloud of points that build a 3D image. This image is the reconstruction of the real scenario.

% parameters
pattype = 'ht';

% reconstruction
[imgp, pitchp, wsp, hsp] = shape_placement_3D_V2(imsize, polyshape, distparams);
Zp = imgp(:,:,3);

% plot the original and reconstruited scenarios

% original 3D scenario
figure(), surf(Zurf)
% hold on, plot3(p(:, 1), p(:, 2), p(:, 3), 'g*')
xlabel('X'), ylabel('Y');
xlim([0 imsize(1)])
ylim([0 imsize(2)])
zlim([-1e-7 4e-7])

% recostruct 3D scenario
figure(), surf(Zp);
xlabel('X'), ylabel('Y');
xlim([0 imsize(1)])
ylim([0 imsize(2)])
zlim([-1e-7 4e-7])

Notes

• If you need to know in detail about the input parameters of each function, please open the file read_sdf.m, shape_placement_3D_V2.m and get_3D_pattern_statistics.m. In that files you can see the source code as well as the explanatory documentation of the function
• Please feel free to review the report.pdf document where we show more examples of this tool.