feat: add base interface of `Unicode plot` and add implementation of `bar plot` #5444

Vinit-Pandit · 2025-02-25T18:00:25Z

Progress #2010

Description

What is the purpose of this pull request?

This pull request:

Add base interface for the unicode plot and implement the bar plot

Related Issues

Does this pull request have any related issues?

This pull request:

progress [RFC]: Development of a Dedicated ASCII Plotter for Benchmark Visualization #2010

Questions

Any questions for reviewers of this pull request?

Yes

How much there is need to line chart in unicode ?
What are the other plots which we may need in future in unicode ?
Does this file structure good ( by the way still in progress ), apart from naming and style and can i go forward with this by adding test and others .

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

Read, understood, and followed the contributing guidelines.

@stdlib-js/reviewers

unicode bar plot

var barchart = require('@stdlib/plot/unicode/static_plots/bar');

/*

var options = {
    xaxis: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14],
    yaxis: [10, 1, 5, 6, 7, 22, 10, 35, 40, 10, 11, 12, 13, 15],
    rows: 20,
    cols: 100,
    barColor: 'Frd',
    labelColor: 'Frd'
};

var inst = new barchart(options);

inst.draw();
inst.render();

line char ( under construcution )

--- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na ---

… plot --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na ---

Vinit-Pandit · 2025-02-25T18:04:24Z

/stdlib update-copyright-years

Vinit-Pandit · 2025-02-26T04:08:25Z

This pr is Intentionally incomplete , i kind of need acknowledgement weather i can go ahead with this or not, I will add the detail detail description which explain this pr .

Vinit-Pandit · 2025-02-27T13:25:47Z

PALLET

Low level Class for unicode/ansi plot

This class maintains a 2D array of characters, colors, and background colors. During the rendering process, these elements are converted into their respective ANSI escape codes.

Features

This class provides methods to manipulate the 2D array, including:

Adding a character, color, or background color to a specific position.
Inserting a string at a specified location.
Rendering the entire array and converting it into ANSI escape codes.

PlotBase

Overview

PlotBase is a foundational class that utilizes the Palette class to structure plots and handle common tasks shared across all plot types. These tasks include:

Managing ticks and labels
Drawing frames
Rendering fundamental structures like rectangles and lines

Drawing Fundamental Structures

The core idea behind drawing each structure is simple:

We pass the structure's dimensions to its respective method.
For example, the drawRectangle method takes four values—two for the height range and two for the width range.
The structure is then stored in terms of its vertices, which are tracked in state variables.
- this._x stores the x-coordinates of the vertices.
- this._y stores the y-coordinates of the vertices.

Example Walkthrough

Drawing a Rectangle

Suppose we need to draw a rectangle.
We call the drawRectangle method of the PlotBase class with parameters xb and yb, representing height and width coordinates:

  drawRectangle( [ 0, 3 ], [ 1, 3 ] );  // Height: (0,3), Width: (1,3)

The method processes these coordinates. In the case of a rectangle, it simply fetches the vertices and stores their x and y coordinates before passing them to the draw method.
The draw method stores the respective data in state variables (this._x, this._y).
Each fundamental structure (e.g., a single rectangle in a bar chart or a single line in a line plot) is stored this way.
Once all structures are stored in the state, we perform the build step:
- This step fills in missing coordinates based on vertices to complete the shape.
- The Palette class method setElement is then used to set characters at all filled coordinates.
- Finally, the render step converts all stored encoding names (color, sketch, and background) into their respective ANSI escape codes.

setNonEnumerableReadOnly( Pallete.prototype, 'setcanvas', function setcanvas() {
	var remainwidth = process.stdout.columns - 0;
	var background;
	var canva = '';
	var color;
	var i;
	var j;

	for ( i = this._sketch.length - 1; i >= 0; i-- ) {
		canva += '\r';
		for ( j = 0; j < this._sketch[ 0 ].length && j < remainwidth; j++ ) {
			// If background color is not same as previous then only we need to change it
			if ( !this.isLegal( i, j - 1 ) || this._backgrounds[ i ][ j ] !== this._backgrounds[ i ][ j - 1 ] ) {
				background = ansiColors[ this._backgrounds[ i ][ j ] ];
				canva += background;
			}
			// If forward color is not same as previous then only we need to change it
			if ( !this.isLegal( i, j - 1 ) || this._colors[ i ][ j ] !== this._colors[ i ][ j - 1 ] ) {
				color = ansiColors[ this._colors[ i ][ j ] ];
				canva += color;
			}
			canva += markers[ this._sketch[ i ][ j ] ];
		}
		canva += ansiColors[ 'def' ];
		canva += '\n';
	}
	this.canva = canva;
	return canva;
} );

every type of plot use this base plot to draw ther visulization all scaling work related to the cordinates also done in the specific plot class
Ex :

barPlot

This class use the basePlot and provide interface to draw a bar chart .
It scale the data points find appropriate width which fit in provided height and width of the container and scale them to the range

Questions

The current implementation is still a prototype, and other plot files, like sparkline, follow a different structure. In sparkline, we first set all the state data, and the main logic is written directly in the render method and in my case i am using the functions it will be good if you can have one look onit !.
- Question: How strictly do I need to follow this structure?
For the line chart, I think we need a more detailed approach. Instead of using █, we should use the half-block characters:
- Examples: ▘, ▖, ▗, ▝
- There are also combination blocks like ▚.
- This would require more logic in the render method to decide whether to use the full block (█) or a more detailed smaller block (▚).
- Question: Is this approach a rabbit hole for our use case? Should we stick with █ as the unit pixel, or would using more detailed blocks (▝) be a viable approach?
Does my current version, which includes features like choosing colors and setting backgrounds, add unnecessary complexity?
- Question: Is this level of customization overkill for our use case? Should we simplify it by removing some of these features?

@kgryte , @Planeshifter

kgryte · 2025-03-04T03:31:48Z

lib/node_modules/@stdlib/plot/unicode/static_plots/bar/default.js

Why the directory "static_plots"? Is there a reason to distinguish between "static" and presumably "dynamic"?

Actully when i see the sparkline code base i thought it take the dynamic inputs means continues from buffer , so the interface i have designe is for static plots only in which we provide full date before rendering , so thats the reason why i have put the name static_plot .

kgryte · 2025-03-04T03:32:38Z

lib/node_modules/@stdlib/plot/unicode/static_plots/bar/default.js

+	out.cols = void 0;
+	out.xaxis = [];
+	out.yaxis = [];
+	out.barColor = 'Fbl';


What is the color naming scheme here? "Fbl" is not immediately obvious.

Fbl stands for forward ( it is name i have seen used in ANSI encoding ) color black , we also have the Bbl for background black . we can change the color schema naming afterwards.

kgryte · 2025-03-04T03:33:11Z

lib/node_modules/@stdlib/plot/unicode/static_plots/bar/example/index.js

+};
+var inst = new barchart(options);
+
+inst.draw();


Why the distinction between "draw" and "render"?

kgryte · 2025-03-04T03:34:48Z