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

Functions

int DSPL_API writebin (void *x, int n, 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_int (int *x, int *y, int n, char *fn)
 Save interger 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...
 

Detailed Description

Function Documentation

◆ writebin()

int writebin ( void *  x,
int  n,
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]nSize of input vector.

[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 328 of file inout.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 491 of file inout.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;
}

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 853 of file inout.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 637 of file inout.c.

void DSPL_API gnuplot_close(void *h)
Close GNUPLOT handle.
Definition: gnuplot.c:325
void DSPL_API gnuplot_cmd(void *h, char *cmd)
Function sends cmd command to GNUPLOT corresponds to h handle.
Definition: gnuplot.c:390
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: inout.c:853
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: array.c:1009
int DSPL_API gnuplot_create(int argc, char *argv[], int w, int h, char *fn_png, void **hplot)
Create GNUPLOT chart.
Definition: gnuplot.c:200