libdspl-2.0
Digital Signal Processing Algorithm Library
Functions
Input and output data from external files.

Functions

int DSPL_API readbin (char *fn, void **x, int *pn, int *pm, int *dtype)
 Read array from the bin-file. More...
 
int DSPL_API writebin (void *x, int n, int m, int dtype, char *fn)
 Save 1D vector to the binary file. More...
 
int DSPL_API writetxt (double *x, double *y, int n, char *fn)
 Save real data \(y(x)\) to the text file fn.
. More...
 
int DSPL_API writetxt_3d (double *x, int nx, double *y, int ny, double *z, char *fn)
 Save data \( z(x,y)\) to the text file fn for 3D surface plotting. More...
 
int DSPL_API writetxt_int (int *x, int *y, int n, char *fn)
 Save interger data \(y(x)\) to the text file fn.
. More...
 

Detailed Description

Function Documentation

◆ readbin()

int readbin ( char *  fn,
void **  x,
int *  pn,
int *  pm,
int *  dtype 
)

Read array from the bin-file.

Function reads real or complex 1D/2D array size n x m from the binary file fn.

File supports 1D and 2D arrays and has follow format: 

type     4 bytes type int.
         Can take on value:
         DAT_DOUBLE,  if x pointer to the real vector;
         DAT_COMPLEX, if x pointer to the complex vector;

n        4 bytes type int.
         Number of array rows.

m        4 bytes type int.
         Number of array columns.
         This parameter equals 1 because this function saves 1D vector.

data     Data in binary raw.
         Data size is:
         n * sizeof(double),    if dtype==DAT_DOUBLE;
         n * sizeof(complex_t), if dtype==DAT_COMPLEX.

Binary file can be used for algorithms verification by external packages like GNU Octave, Matlab, Python because the function reads data without loss of accuracy.

Parameters
[in]fnFile name.

[in]xPointer to the data memory.
Memory will be allocated for the output array.
[in]pnrows number.

[in]mPointer to the columns number.

[in]dtypeType of data.
Can be one of follow:
DAT_DOUBLE – real data;
DAT_COMPLEX – complex data.

Returns
RES_OK if file read successfully.
Else code error.

Write bin-file in GNU Octave and Matlab:

function res = writebin(x, type, fn)
if(type~=0 && type~=1)
res = 2;
return;
end
fid = fopen(fn, 'w');
if(~fid)
error('cannot to open file');
end
n = size(x, 1);
m = size(x, 2);
count = fwrite(fid, type, 'int32');
if(count ~= 1)
res = 1;
return;
end
count = fwrite(fid, n, 'int32');
if(count ~= 1)
fclose(fid);
res = 1;
return;
end
count = fwrite(fid, m, 'int32');
if(count ~= 1)
res = 1;
fclose(fid);
return;
end
flag = 0;
if(type==0)
count = fwrite(fid, x, 'double');
if(count ~= n*m)
res = 1;
fclose(fid);
return;
end
flag = 1;
else
y = reshape(x, n*m, 1);
z = zeros(2*n*m, 1);
z(1:2:end) = real(y);
z(2:2:end) = imag(y);
count = fwrite(fid, z, 'double');
if(count ~= 2*n*m)
res = 1;
fclose(fid);
return;
end
flag = 1;
end
if(flag == 0)
res = 3;
else
res = 0;
end
fclose(fid);
end
writebin
int DSPL_API writebin(void *x, int n, int m, int dtype, char *fn)
Save 1D vector to the binary file.
Definition: writebin.c:217

Example:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "dspl.h"
#define N 6
int main(int argc, char* argv[])
{
void* hdspl; /* DSPL handle */
random_t rnd = {0}; /* random structure */
hdspl = dspl_load(); /* Load DSPL function */
/* input vector */
double x[N];
double *y = NULL;
int err, n, m, t;
/* Generate random input vector */
err = random_init(&rnd, RAND_TYPE_MRG32K3A, NULL);
if(err != RES_OK)
goto exit_label;
err = randn(x, N, 0.0, 1.0, &rnd);
if(err != RES_OK)
goto exit_label;
/* Write input vector x to the bin file x.bin */
err = writebin(x, N, 1, DAT_DOUBLE, "x.bin");
if(err != RES_OK)
goto exit_label;
/* Read x.bin to the y vector */
err = readbin("x.bin", (void**)&y, &n, &m, &t);
if(err != RES_OK)
goto exit_label;
/*Print x and y vectors */
printf("n = %d, m = %d, t = %d\n", n, m, t);
for(t = 0; t < n; t++)
printf("%+8.4f, %+8.4f\n", x[t], y[t]);
exit_label:
if(y)
free(y);
/* free dspl handle */
dspl_free(hdspl);
return 0;
}
RES_OK
#define RES_OK
The function completed correctly. No errors.
Definition: dspl.h:558
readbin
int DSPL_API readbin(char *fn, void **x, int *pn, int *pm, int *dtype)
Read array from the bin-file.
Definition: readbin.c:314
random_init
int DSPL_API random_init(random_t *prnd, int type, void *seed)
Pseudorandom numbers generators initialization.
Definition: random_init.c:120
dspl_load
void * dspl_load()
Perform dynamic linking and load libdspl-2.0 functions.
dspl_free
void dspl_free(void *handle)
Cleans up the previously linked DSPL-2.0 dynamic library.
random_t
Definition: dspl.h:350
Author
Sergey Bakhurin www.dsplib.org

Definition at line 314 of file readbin.c.

◆ writebin()

int writebin ( void *  x,
int  n,
int  m,
int  dtype,
char *  fn 
)

Save 1D vector to the binary file.

Function saves real or complex 1D vector size n to the binary file fn.

File format supports 1D and 2D arrays and has follow format: 

type     4 bytes type int.
         Can take on value:
         DAT_DOUBLE,  if x pointer to the real vector;
         DAT_COMPLEX, if x pointer to the complex vector;

n        4 bytes type int.
         Number of array rows.

m        4 bytes type int.
         Number of array columns.
         This parameter equals 1 because this function saves 1D vector.

data     Data in binary raw.
         Data size is:
         n * sizeof(double),    if dtype==DAT_DOUBLE;
         n * sizeof(complex_t), if dtype==DAT_COMPLEX.

Binary file can be used for algorithms verification by external packages like GNU Octave, Matlab, Python because the function writes to a file without loss of accuracy.

Parameters
[in]xPointer to the input vector.
Vector size is [n x 1].

[in]nRows number.

[in]mColumns number.

[in]dtypeType of data.
Can be one of follow:
DAT_DOUBLE – real data;
DAT_COMPLEX – complex data.

[in]fnFile name.

Returns
RES_OK if file is saved successfully.
Else code error.

Reading saved binary file from GNU Octave or Matlab:

function [dat, n, m] = readbin(fn)
fid = fopen(fn);
if(~fid)
error('cannot to open file');
end
type = fread(fid, 1, 'int32');
n = fread(fid, 1, 'int32');
m = fread(fid, 1, 'int32');
if(type==0)
dat = fread(fid, [n*m, 1], 'double');
end
if(type==1)
y = fread(fid, [n*m*2, 1], 'double');
dat = y(1:2:end) + 1i * y(2:2:end);
end
dat = reshape(dat, n, m);
fclose(fid);
end
Author
Sergey Bakhurin www.dsplib.org

Definition at line 217 of file writebin.c.

◆ writetxt()

int writetxt ( double *  x,
double *  y,
int  n,
char *  fn 
)

Save real data \(y(x)\) to the text file fn.
.

File format is:

x[0]        y[0]
x[1]        y[1]
...         ...
x[n-1]    y[n-1]

Text file can be used to plotting data with a third-party program for example, the GNUPLOT package (see Plotting data by Gnuplot interface.).

Parameters
[in]xPointer to the vector x.
Vector size is [n x 1].

[in]yPointer to the vector y.
Vector size is [n x 1].
This pointer can be NULL. File will have only one column corresponds to x vector in this case.

[in]nSize of vectors x and y.

[in]fnFile name.

Returns
RES_OK if file is saved successfully.
Else code error.
Note
This function rounds data when writing to a file. So, it is not recommended to use it to verify algorithms.
Author
Sergey Bakhurin www.dsplib.org

Definition at line 122 of file writetxt.c.

◆ writetxt_3d()

int writetxt_3d ( double *  x,
int  nx,
double *  y,
int  ny,
double *  z,
char *  fn 
)

Save data \( z(x,y)\) to the text file fn for 3D surface plotting.

Function \( z(x,y)\) describes as matrix z[x[n], y[n]] as it showed on the follow figure:

Matrix z writen in the memory by columns as it it showed on the figure by red arrow.
Text file fas follow format: 

x[0]        y[0]        z[0, 0]
x[1]        y[0]        z[1, 0]
x[2]        y[0]        z[2, 0]
...         ...         ...
x[nx-1] y[0]        z[nx-1, 0]

x[0]        y[1]        z[0, 1]
x[1]        y[1]        z[1, 1]
x[2]        y[1]        z[2, 1]
...         ...         ...
x[nx-1] y[1]        z[nx-1, 1]

...         ...         ...
...         ...         ...
...         ...         ...

x[0]        y[ny-1] z[0, ny-1]
x[1]        y[ny-1] z[1, ny-1]
x[2]        y[ny-1] z[2, ny-1]
...         ...         ...
x[nx-1] y[ny-1] z[nx-1, ny-1]

Each z matrix value is writen on individual line corresponds to x and y values. Matrix columns are separated from each other by an empty line.

The file can be used to build a 3D surface with a third-party program for example, the GNUPLOT package (see Plotting data by Gnuplot interface.). Also this format supported by pgfplot3d packages of the Latex system.

Parameters
[in]xPointer to the vector x.
Vector size is [nx x 1].

[in]nxSize of vector x.

[in]yPointer to the vector y.
Vector size is [ny x 1].

[in]nySize of vector y.

[in]zPointer to the matrix z(x, y).
Size of matrix is [nx x ny].

[in]fn3D data file name.

Returns
RES_OK if file is saved successfully.
Else code error.

Example of 3D surface plotting:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include "dspl.h"
#define NX 20
#define NY 30
int main(int argc, char* argv[])
{
void* hdspl; /* DSPL handle */
void* hplot; /* GNUPLOT handles */
hdspl = dspl_load(); /* Load DSPL function */
double x[NX];
double y[NY];
double z[NX * NY];
int n, m;
int err;
/* x vector from -2 to 2 */
linspace(-2.0, 2.0, NX, DSPL_SYMMETRIC, x);
/* y vector from -2.5 to 2.5 */
linspace(-2.5, 2.5, NY, DSPL_SYMMETRIC, y);
/* z(x,y) = x * exp(-x^2 - y^2) */
for(n = 0; n < NX; n++)
{
for(m = 0; m < NY; m++)
{
z[n + m*NX] = x[n]*exp(-x[n]*x[n] - y[m]*y[m]);
}
}
/* Save to files "dat/data3d.txt" */
err = writetxt_3d(x, NX, y, NY, z, "dat/data3d.txt");
printf("writetxt_3d error 0x%8x\n", err);
/* plotting 3d surface by GNUPLOT */
/* Create window 0 */
err = gnuplot_create(argc, argv, 560, 480, "img/writetxt_3d.png", &hplot);
printf("GNUPLOT err = %d\n", err);
gnuplot_cmd(hplot, "set pm3d implicit at s");
gnuplot_cmd(hplot, "set view 50, 340, 1, 1");
gnuplot_cmd(hplot, "set xlabel 'x'");
gnuplot_cmd(hplot, "set ylabel 'y'");
gnuplot_cmd(hplot, "splot 'dat/data3d.txt' with lines");
gnuplot_close(hplot);
dspl_free(hdspl); /* free dspl handle */
return 0;
}
linspace
int DSPL_API linspace(double x0, double x1, int n, int type, double *x)
Function fills a vector with n linearly spaced elements between x0 and x1.
Definition: linspace.c:169
writetxt_3d
int DSPL_API writetxt_3d(double *x, int nx, double *y, int ny, double *z, char *fn)
Save data to the text file fn for 3D surface plotting.
Definition: writetxt_3d.c:214
gnuplot_close
void DSPL_API gnuplot_close(void *h)
Close GNUPLOT handle.
Definition: gnuplot_close.c:80
gnuplot_create
int DSPL_API gnuplot_create(int argc, char *argv[], int w, int h, char *fn_png, void **hplot)
Create GNUPLOT chart.
Definition: gnuplot_create.c:202
gnuplot_cmd
void DSPL_API gnuplot_cmd(void *h, char *cmd)
Function sends cmd command to GNUPLOT corresponds to h handle.
Definition: gnuplot_cmd.c:82

Program calcultes function

\[ z(x,y) = x \exp(-x^2 -y^2) \]

and save data to the dat/data3d.txt file.
In addition, GNUPLOT built a 3D surface by data saved to the dat/data3d.txt file:

Author
Sergey Bakhurin www.dsplib.org

Definition at line 214 of file writetxt_3d.c.

◆ writetxt_int()

int writetxt_int ( int *  x,
int *  y,
int  n,
char *  fn 
)

Save interger data \(y(x)\) to the text file fn.
.

File format

x[0]        y[0]
x[1]        y[1]
...         ...
x[n-1]    y[n-1]

Text file can be used to plotting data with a third-party program for example, the GNUPLOT package (see Plotting data by Gnuplot interface.).

Parameters
[in]xPointer to the interger vector x.
Vector size is [n x 1].

[in]yPointer to the interger vector y.
Vector size is [n x 1].
This pointer can be NULL. File will have only one column corresponds to x vector in this case.

[in]nSize of vectors x and y.

[in]fnFile name.

Returns
RES_OK if file is saved successfully.
Else code error.
Author
Sergey Bakhurin www.dsplib.org

Definition at line 115 of file writetxt_int.c.

Generated on Wed Jan 5 2022 12:44:37 for libdspl-2.0 by   doxygen 1.9.2
libdspl-2.0 documentation is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.